6928 documentation of mp reactive messaging stream operators 3-8

6928 documentation of mp reactive messaging stream operators 3-8

#6928

modules/ROOT/pages/liberty-kafka-connector-channel-properties.adoc

@@ -8,19 +8,18 @@
 //
 :page-layout: general-reference
 :page-type: general
-:page-description: The Liberty-kafka connector offers a range of properties to fine-tune its operation. You can set these properties on the `Liberty-kafka` connector to define certain behaviors during operation.
+:page-description: The Liberty-Kafka connector offers a range of properties to fine-tune its operation. You can set these properties on the `liberty-kafka` connector to define certain behaviors during operation.
 :page-categories: MicroProfile Reactive Messaging
-:seo-title: Liberty-kafka connector options and channel properties
-:seo-description: The Liberty-kafka connector offers a range of properties to fine-tune its operation. You can set these properties on the `Liberty-kafka` connector to define certain behaviors during operation.
-
+:seo-title: Liberty-Kafka connector options and channel properties
+:seo-description: The Liberty-Kafka connector offers a range of properties to fine-tune its operation. You can set these properties on the `liberty-kafka` connector to define certain behaviors during operation.
 
 
 [#connectoroptionschannelprop]
-= Liberty-kafka connector options and channel properties
+= Liberty-Kafka connector options and channel properties
 
-The `Liberty-kafka` connector offers a range of properties to fine-tune its operation. You can set these properties on the `Liberty-kafka` connector to define certain behaviors during operation.
+The `liberty-kafka` connector offers a range of properties to fine-tune its operation. You can set these properties on the `liberty-kafka` connector to define certain behaviors during operation.
 
-You can use all these options as attributes on either the connector or a channel that uses the `Liberty-kafka` connector. If you specify the option on both the channel and the connector, the channel takes precedence.
+You can use all these options as attributes on either the connector or a channel that uses the `liberty-kafka` connector. If you specify the option on both the channel and the connector, the channel takes precedence.
 
 .Properties supported by the `liberty-kafka` connector for incoming channels
 [cols="a,a,a",width="100%"]
@@ -45,7 +44,7 @@ You can use all these options as attributes on either the connector or a channel
  {empty} +
 If the value of `fast.ack` is `false`, the acknowledgment is not reported as complete until the partition offset is committed to the Kafka broker. If an error occurs during this process, then the acknowledgment is reported as failed.
  {empty} +
-If the value of `fast.ack` is `true`, and the acknowledgment is reported as complete when the Kafka Connector receives the acknowledgment signal.
+If the value of `fast.ack` is `true`, and the acknowledgment is reported as complete when the Kafka connector receives the acknowledgment signal.
 
 |context.service
 |If the `concurrent-x.y` feature is enabled. the default context service is used.
@@ -61,6 +60,18 @@ This setting specifies the Context Service that is used for Asynchronous tasks.
 
 |===
 
+== fast.ack
+Properties like `fast.ack` allow for control over message acknowledgment processes, improving the efficiency of message processing. 
+
+In the following example, in the `microprofile-config.properties` file of the application, the `fast.ack` setting is defaulted to `false` for the connector, affecting all channels in the application. However, for a distinct incoming channel called `foo`, this setting is overridden to `true`. This alteration favors a quicker acknowledgment approach, which enhances the handling performance for messages that arrive on this channel.
+
+----
+mp.messaging.connector.liberty-kafka.fast.ack=false
+
+mp.messaging.incoming.foo.connector=liberty-kafka
+mp.messaging.incoming.foo.fast.ack=true
+----
+
 
 .Properties supported by the `liberty-kafka` connector for outgoing channels
 [cols="a,a,a",width="100%"]
@@ -87,35 +98,18 @@ This setting specifies the Context Service that is used for Asynchronous tasks.
 |===
 
 
-== fast.ack
-Properties like `fast.ack` allow for control over message acknowledgment processes, improving the efficiency of message processing. 
-
-In the following example, in the `microprofile-config.properties` file of the application, the `fast.ack` setting is defaulted to `false` for the connector, affecting all channels in the application. However, for a distinct incoming channel called `foo`, this setting is overridden to `true`. This alteration favors a quicker acknowledgment approach, which enhances the handling performance for messages that arrive on this channel.
-
-----
-mp.messaging.connector.liberty-kafka.fast.ack=false
-
-mp.messaging.incoming.foo.connector=liberty-kafka
-mp.messaging.incoming.foo.fast.ack=true
-----
-
 == context.service
 The `context.service` attribute specifies the Context Service for asynchronous operations, critical for performance tuning. 
-
 Context Services that are defined within the application itself cannot be used with the `liberty-kafka` connector. 
 
 In the following example, the `server.xml` file defines three different context services, each with a unique identifier (`rst`, `uvw`, and `xyz`).
-
-server.xml
 ----
 <contextService id=“rst”/>
 <contextService id=“uvw”/>
 <contextService id=“xyz”/>
 ----
 
 The `microprofile-config.properties` file is part of the application's configuration and specifies how MicroProfile features should be used within the application.
-
-microprofile-config.properties
 ----
 mp.messaging.connector.liberty-kafka.context.service=rst
 
@@ -126,12 +120,10 @@ mp.messaging.outgoing.bar.connector=liberty-kafka
 mp.messaging.outgoing.bar.context.service=xyz
 ----
 
-The property `mp.messaging.connector.liberty-kafka.context.service=rst` indicates that the Kafka connector that is used for handling messaging between services uses the `rst`` context service by default for its operations.
+In the example, the property `mp.messaging.connector.liberty-kafka.context.service=rst` indicates that the Kafka connector that is used for handling messaging between services uses the `rst` context service by default for its operations.
 
 The application has three channels (`def`, `foo`, and `bar`), which are logical endpoints for incoming and outgoing messages. The configuration for these channels specifies which Kafka connector to use (`liberty-kafka`) and for two of the channels (`foo` and `bar`), overrides the default context service with their own (`uvw` and `xyz`, respectively).
-
 The `def` channel does not specify its own `context.service`, so it inherits the default one (`rst`) defined at the connector level.
 
 By defining separate context services, the application can isolate certain operations or configurations, which can be useful in complex applications or during integration with external systems.
-
 These configurations demonstrate the flexibility and control that you have over message processing in Open Liberty applications.

modules/ROOT/pages/liberty-kafka-connector-config-security.adoc

@@ -10,24 +10,23 @@
 :page-type: general
 :page-description: For configuring the Kafka connector and security in Open Liberty, you can focus on the distinction between channel-specific and connector-wide properties for tailored messaging behavior. 
 :page-categories: MicroProfile Reactive Messaging
-:seo-title: Kafka connector configuration and security
+:seo-title: Kafka connector security configuration
 :seo-description: The integration of MicroProfile Reactive Messaging with Apache Kafka in Open Liberty applications is a significant development in cloud-native microservice designs as it provides an efficient method of asynchronous communication.
 
 
 [#kcconfsec]
-= Kafka connector configuration and security
+= Kafka connector security configuration 
 
 For configuring the Kafka connector and security in Open Liberty, you can focus on the distinction between channel-specific and connector-wide properties for tailored messaging behavior. 
-
 Connector-wide properties, like `bootstrap.servers` apply globally, whereas channel-specific properties, such as `topic` or `group.id`, customize the individual channel behavior. 
 
 For security, Open Liberty supports multiple authentication methods: 
 
 * <<#ssl,Secure Sockets Layer (SSL)>>
-* <<#sasl,Simple Authentication and Security Layer/PLAIN (SASL/PLAIN)>>
+* <<#sasl,Simple Authentication and Security Layer (SASL)/PLAIN >>
 * <<#mtls,Mutual TLS (mTLS)>>
 
-To make sure of secure communication with Kafka brokers, you can set the appropriate security properties within the `microprofile-config.properties` file, facilitating the support of any of the authentication methods.
+To make sure of secure communication with Kafka brokers, you can set the appropriate security properties within the xref:microprofile-config-properties.adoc#react[microprofile-config.properties] file, facilitating the support of any of the authentication methods.
 
 [#ssl]
 == Secure Sockets Layer (SSL)
@@ -42,11 +41,10 @@ mp.messaging.connector.liberty-kafka.ssl.truststore.location=kafka-truststore.jk
 ----
 
 [#sasl]
-== Simple Authentication and Security Layer/PLAIN (SASL/PLAIN)
-
-The following example demonstrates the setup of SASL_SSL (Simple Authentication and Security Layer over SSL) for authentication with either the Kafka Plain Login Module or the Open Liberty Kafka Login Module.
+== Simple Authentication and Security Layer (SASL)/PLAIN 
 
-This configuration enables encrypted communication and authentication with Kafka brokers. It uses properties set in the `microprofile-config.properties` file to support different authentication methods, including password encryption with Open Liberty xref:reference:command/securityUtility-encode.adoc[securityUtility encode]. Applications can maintain the confidentiality and integrity of messages, making sure that secure data flow across distributed systems.
+The following example demonstrates the setup of the SASL/PLAIN authentication with either the Open Liberty Kafka Login Module or the Kafka Plain Login Module.
+This configuration enables encrypted communication and authentication with Kafka brokers. It uses properties set in the `microprofile-config.properties` file to support different authentication methods, including password encryption with Open Liberty xref:reference:command/securityUtility-encode.adoc[securityUtility encode]. Applications can maintain the confidentiality and integrity of messages, ensuring secure data flow across distributed systems.
 
 - Authenticating with Open Liberty's Kafka Login Module that can use passwords encoded by Open Liberty xref:reference:command/securityUtility-encode.adoc[securityUtility encode] on a per channel basis.
 ----
@@ -69,7 +67,7 @@ mp.messaging.outgoing.aes-test-out.ssl.truststore.location=kafka-truststore.jks
 mp.messaging.outgoing.aes-test-out.ssl.truststore.password=kafka-teststore
 ----
 
-- Authenticating with Kafka's Plain Login Module
+- Authenticating with Kafka's Plain Login Module.
 ----
 mp.messaging.connector.liberty-kafka.security.protocol=SASL_SSL
 mp.messaging.connector.liberty-kafka.bootstrap.servers=SASL_SSL\://kafka-boostrap-server\:34696
@@ -106,3 +104,5 @@ mp.messaging.outgoing.test-out.topic=outgoing-topic
 mp.messaging.outgoing.test-out.ssl.keystore.location=kafka-keystore2.jks
 mp.messaging.outgoing.test-out.ssl.keystore.password=kafka-teststore
 ----
+
+Using Open Liberty's support for multiple authentication methods, including SSL, SASL/PLAIN, and mTLS, enhances the security of data in transit and ensures the authentication of both clients and servers. This careful attention to configuration and security contributes to the creation of a resilient architecture. Such an architecture can protect sensitive information and maintain the integrity of communication between microservices.

modules/ROOT/pages/liberty-kafka-connector.adoc

@@ -19,13 +19,13 @@ Integrating MicroProfile Reactive Messaging and Apache Kafka with the `liberty-k
 
 The following sections describe how to intergrate MicroProfile Reactive Messaging with Apache Kafka to send messages within and between applications:
 
-* <<#configuration,Configure the Liberty-kafka connector>>
+* <<#configuration,Configure the Liberty-Kafka connector>>
 * <<#sendrecemessages,Sending and receiving messages among applications by using connectors>>
 * <<#troubleshooting,Troubleshooting>>
 
 
 [#configuration]
-== Configure the Liberty-kafka connector
+== Configure the Liberty-Kafka connector
 
 The `liberty-kafka` connector enables applications to send and receive messages from an Apache Kafka broker. It uses MicroProfile Reactive Messaging standards for robust, asynchronous communication in microservices architectures. 
 
@@ -35,60 +35,53 @@ You can fine-tune your application's interaction with Kafka by configuring the c
 mp.messaging.connector.liberty-kafka.bootstrap.servers=localhost:9082
 ----
 
-By configuring a MicroProfile application as shown in the example, to connect to a Kafka broker at `localhost:9082` for messaging. The result is the application's ability to produce and receive messages through Kafka, facilitating event-driven communication.
+By configuring a MicroProfile application as shown in the example, to connect to a Kafka broker at `localhost:9082` for messaging. The application is able to send and receive messages through Kafka, facilitating event-driven communication.
 
 
 You can define a channel to use this connector, directly linking a message channel to Kafka, as shown in the following example.
-
 ----
 mp.messaging.incoming.myChannel.connector=liberty-kafka
 ----
-
 By setting up a channel as shown in the example, you connect a message channel directly to Kafka, which gives you precise control over the messaging channels. You can specify attributes such as `bootstrap.servers` for connection and `topic` for message direction, enhancing your application's ability to scale and remain robust by efficiently managing messages.
 
-
 Integrate Kafka with Open Liberty by following these steps:
 
-1. <<#connection,Establish a stable connection with Kafka brokers>>
-2. <<#define,Create specific channels for sending and receiving messages>>
-3. <<#includelib,Incorporate Kafka client libraries to the application>>
-
+1. <<#connection,Configure the Kafka broker connection>>
+2. <<#define,Define channels for messaging>>
+3. <<#includelib,Include Kafka client libraries>>
 
 
 [#connection]
-=== Configure Kafka Broker Connection
+=== 1. Configure the Kafka broker connection
 
 In the `microprofile-config.properties` file, specify the Kafka broker addresses to establish a connection, which indicates where your Kafka broker is hosted.
-
 ----
 mp.messaging.connector.liberty-kafka.bootstrap.servers=myKafkaBroker:9092
 ----
 
-
 [#define]
-=== Define Channels for Messaging
+=== 2. Define channels for messaging
 
 - To specify the Kafka topic from which messages are received, create a channel for incoming messages.
-+
 ----
 mp.messaging.incoming.myChannel.connector=liberty-kafka
 mp.messaging.incoming.myChannel.topic=myTopicName
 ----
+
 - To specify the Kafka topic from which messages are sent, create a channel for outgoing messages.
-+
 ----
 mp.messaging.outgoing.myChannel.connector=liberty-kafka
 mp.messaging.outgoing.myChannel.topic=myTopicName.
 ----
 
-For more information on `liberty-kafka` connector options and channel properties, see xref:liberty-kafka-connector-channel-properties.adoc[Liberty-kafka connector options and channel properties].
+For more information on Liberty-Kafka connector options and channel properties, see xref:liberty-kafka-connector-channel-properties.adoc[Liberty-Kafka connector options and channel properties].
 
 [#includelib]
-=== Include Kafka Client Libraries
+=== 3. Include Kafka client libraries
 
 To integrate Kafka into your application environment by using Open Liberty, choose one of the following methods based on your requirement.
 
-==== Include Kafka Libraries as an Application Dependency
+==== Include Kafka libraries as an application dependency
 
 To use the Kafka connector provided by Open Liberty, you must include the Kafka client API jar in your application.
 
@@ -105,14 +98,12 @@ If you are building your application with Maven, add the Kafka client dependency
 
 This approach integrates Kafka client libraries directly into your application. It does not require any additional server configuration for permissions, simplifying deployment and configuration management.
 
-==== Include Kafka Libraries as a Shared Library
+==== Include Kafka libraries as a shared library
 
 You can integrate Kafka client libraries as a shared resource within the Open Liberty server. This approach is useful for situations where several applications on the same server instance require the Kafka client libraries. It effectively minimizes duplication.
 
 However, if Kafka client libraries are used as a xref:class-loader-library-config.adoc#shrdLib[shared library], you must explicitly grant the necessary Java permissions for the libraries to function correctly. These permissions allow the Kafka client to connect to Kafka brokers, read system properties, and access or modify security properties.
 
-For more information on security and authentication methods, see xref:liberty-kafka-connector-config-security.adoc[Kafka connector configuration and security].
-
 To configure these permissions, you can use the `server.xml` configuration file. The following example demonstrates how to grant the necessary permissions to a Kafka client library that is specified as a shared library:
 
 [source,XML]
@@ -156,6 +147,8 @@ To configure these permissions, you can use the `server.xml` configuration file.
    <javaPermission codebase="${kafkaCodebase}" className="javax.security.auth.AuthPermission" name="modifyPrivateCredentials"/>
 ----
 
+For more information on security and authentication methods, see xref:liberty-kafka-connector-config-security.adoc[Kafka connector security configuration].
+
 
 [#sendrecemessages]
 == Sending and receiving messages among applications by using connectors
@@ -187,15 +180,14 @@ The example uses the `liberty-kafka` connector to manage the connection between
 
 The application gains the ability to offload messages to the Kafka topic `bar`. This approach to distributed messaging enhances scalability and flexibility in handling data flows.
 
-For more information, see link:/guides/microprofile-reactive-messaging.html#creating-the-consumer-in-the-inventory-microservice[Creating the consumer in the inventory microservice].
-
+For more information on `liberty-kafka` connector options and channel properties, see xref:liberty-kafka-connector-channel-properties.adoc[Liberty-kafka connector options and channel properties].
 
 [#troubleshooting]
 == Troubleshooting
 
 To troubleshoot the `liberty-kafka` connector, address key issues like Kafka connectivity, managing multiple server instances, and giving distinct identifiers to producers and consumers. Make sure that the `bootstrap.servers` are configured correctly for connection. Each consumer has a distinct `group.id` to prevent conflicts, and producers need a unique `client.id` to av     o id identifier overlap.
 
-== = Multiple server instances
+=== Multiple server instances
 
 If you start multiple instances of Open Liberty with the same application, you must assign a distinct `group.id` to each channel for every server instance. This requirement applies to all incoming channels. Without a distinct `group.id` on each server instance, the server will block any new connections to a topic after the first connection is established. This policy makes sure that each connection to a topic is distinct and properly managed across all server instances.
 
@@ -213,6 +205,8 @@ Specifying either attribute on the `liberty-kafka` Connector does not resolve th
 
 These steps are designed to diagnose and resolve common challenges that are encountered integrating Kafka with Open Liberty. They help in facilitating the smooth functioning of your microservices architecture.
 
+For more information, see link:/guides/microprofile-reactive-messaging.html#creating-the-consumer-in-the-inventory-microservice[Creating the consumer in the inventory microservice] in the Creating reactive Java microservices guide.
+
 For more information on Apache Kafka, see the https://kafka.apache.org/documentation.html#gettingStarted[Apache Kafka documentation].