diff --git a/documentation/src/main/doc/modules/ROOT/pages/concepts.adoc b/documentation/src/main/doc/modules/ROOT/pages/concepts.adoc index 8471d5cabc..e60c18e469 100644 --- a/documentation/src/main/doc/modules/ROOT/pages/concepts.adoc +++ b/documentation/src/main/doc/modules/ROOT/pages/concepts.adoc @@ -1,15 +1,15 @@ = Concepts -When dealing with event-driven or data streaming application, there are a few concepts and vocabulary to introduce. +When dealing with event-driven or data streaming applications, there are a few concepts and vocabulary to introduce. [#messages] == Messages, Payload, Metadata A `Message` is an _envelope_ around a `payload`. -Your application is going to receive, process and send `Messages`. +Your application is going to receive, process, and send `Messages`. -These `Messages` can be generated by your application, or are retrieved from a message broker. -They can also be consumed by your application, or sent to a message broker. +Your application's logic can generate these `Messages` or receive them from a message broker. +They can also be consumed by your application or sent to a message broker. image::messages.png[] @@ -22,12 +22,12 @@ include::example$messages/MessageExamples.java[tag=message] ---- As you can see in the previous snippet, `Messages` can also have _metadata_. -_Metadata_ are a way to extend messages with additional data. +_Metadata_ is a way to extend messages with additional data. It can be metadata related to the message broker ({javadoc-base}/apidocs/io/smallrye/reactive/messaging/kafka/KafkaMessageMetadata.html[`KafkaMessageMetadata`] for instance), or contain operational data (such as tracing metadata), or business-related data. NOTE: When retrieving metadata, you get an `Optional` as it may not be present. -TIP: Metadata are also used to influence the outbound dispatching (how the message is going to be sent to the broker). +TIP: Metadata is also used to influence the outbound dispatching (how the message will be sent to the broker). [#channels] == Channels and Streams @@ -38,7 +38,7 @@ A _channel_ is a virtual destination identified by a name. image::channels.png[] -SmallRye Reactive Messaging connects the component to channel they read and to channel they populate. +SmallRye Reactive Messaging connects the component to the channel they read and to the channel they populate. The resulting structure is a stream: Messages flow between components through channels. [NOTE] @@ -58,16 +58,21 @@ It also means that <> are intended to use non-blocking IO to interac Your application is interacting with messaging brokers or event backbone using _connectors_. A _connector_ is a piece of code that connects to a broker and: -1. subscribe / poll / receive messages from the broker and propagate them to the application -2. send / write / dispatch messages provided by the application to the broker +1. subscribe/poll/receive messages from the broker and propagate them to the application +2. send/write/dispatch messages provided by the application to the broker -To achieve this, connectors are configured to map incoming messages to a specific _channel_ (consumed by the application) and to collect outgoing messages sent to a specific channel by the application. +Connectors are configured to map incoming messages to a specific _channel_ (consumed by the application) and collect outgoing messages sent to a specific channel. These collected messages are sent to the external broker. image::connectors.png[] -Each connector is dedicated to a technology. -For example a Kafka Connector only deal with Kafka. +Each connector is dedicated to a specific technology. +For example, a Kafka Connector only deals with Kafka. +You don't necessarily need a connector. +When your application does not use connectors, everything happens _in-memory_, and the streams are created by chaining methods altogether. +Each chain is still a reactive stream and enforces the back-pressure protocol. +When you don't use connectors, you need to make sure the chain is complete, meaning it starts with a message source, and it ends with a sink. +In other words, you need to generate messages from within the application (using a method with only `@Outgoing`, or an `Emitter`) and consume the messages from within the application (using a method with only `@Incoming` or using an unmanaged stream).