Merge pull request #269 from akka/ennru-brokers

docs: revise message brokers page structure

docs/src/modules/java/nav.adoc

@@ -11,7 +11,7 @@
 *** xref:consuming-producing.adoc[Consumers]
 ** Integrations
 *** xref:component-and-service-calls.adoc[]
-*** xref:operations:projects/message-brokers.adoc[]
+*** xref:message-brokers.adoc[]
 *** xref:streaming.adoc[]
 ** Setup and configuration
 *** xref:setup-and-dependency-injection.adoc[]

docs/src/modules/java/pages/consuming-producing.adoc

@@ -2,7 +2,7 @@
 
 include::ROOT:partial$include.adoc[]
 
-image:ROOT:consumer.png[Consumer,width=100,float=left]  Consuming and producing allow stream based interaction between services and also with the outside world. Consuming or publishing a stream of events is a common Microservices pattern. The source of events can be the journal of an Event Sourced Entity, the Key Value Entity state changes, a https://cloud.google.com/pubsub/docs/overview[Google Cloud Pub/Sub, window="new"] or https://kafka.apache.org/[Apache Kafka, window="new"] topic for asynchronous messaging between services.
+image:ROOT:consumer.png[Consumer,width=100,float=left]  Consuming or producing a stream of events is a common Microservices pattern. It allows stream-based interaction between Akka services and other systems. The source of events can be the journal of an Event Sourced Entity, state changes in a Key Value Entity, or a message broker topic.
 
 In this section, we will explore how you can use a Consumer component to:
 
@@ -107,9 +107,9 @@ include::example$event-sourced-customer-registry-subscriber/src/main/java/custom
 <4> Consumer group is required in case many consumers subscribing to the same stream.
 <5> Handler method per message type that the stream may contain.
 
-TIP: If you're looking to test this locally, you will likely need to run the 2 services with different ports. For more details, consult xref:running-locally.adoc#_running_multiple_services_locally[Running multiple services].
+TIP: If you're looking to test this locally, you will likely need to run the 2 services with different ports. For more details, consult xref:running-locally.adoc#multiple_services[Running multiple services].
 
-[#_consume_from_a_message_broker_topic]
+[#consume_topic]
 == Consume from a message broker Topic
 
 To receive messages from a Google Cloud Pub/Sub or Apache Kafka topic, annotate the Consumer class with `@Consume.FromTopic` and specify the topic name.
@@ -160,7 +160,8 @@ include::example$event-sourced-counter-brokers/src/main/java/counter/application
 
 If a Consumer produce messages of `byte[]` type to a topic, the messages published to the topic will have content-type `application/octet-stream`.
 
-== Producing to a Topic
+[#topic_producing]
+== Producing to a message broker Topic
 
 Producing to a topic is the same as producing to a stream in service to service eventing. The only difference is the `@Produce.ToTopic` annotation. Used to set a destination topic name.
 
@@ -308,7 +309,7 @@ include::example$event-sourced-counter-brokers/src/test/java/counter/application
 
 == Multi-region replication
 
-Consumers are not replicated directly in the same way as for example xref:event-sourced-entities.adoc#_replication[Event Sourced Entity replication]. A Consumer receive events from entities in the same service, or another service, in the same region. The entities will replicate all events across regions and identical processing can occur in the consumers of each region.
+Consumers are not replicated directly in the same way as for example xref:event-sourced-entities.adoc#_replication[Event Sourced Entity replication]. A Consumer receives events from entities in the same service, or another service, in the same region. The entities will replicate all events across regions and identical processing can occur in the consumers of each region.
 
 The origin of an event is the region where a message was first created. You can see the origin from `messageContext().hasLocalOrigin()` or `messageContext().originRegion()` and perform conditional processing of the event depending on the origin, such as ignoring events from other regions than the local region where the Consumer is running. The local region can be retrieved with `messageContext().selfRegion()`.
 

docs/src/modules/java/pages/http-endpoints.adoc

@@ -156,7 +156,7 @@ include::example$event-sourced-customer-registry-subscriber/src/main/java/custom
 <4> The result of a request is either `CompletionStage<T>` with the result
 <5> Once the response arrives, turn it into our own response.
 
-TIP: If you're looking to test this locally, you will likely need to run the 2 services with different ports. For more details, consult xref:running-locally.adoc#_running_multiple_services_locally[Running multiple services].
+TIP: If you're looking to test this locally, you will likely need to run the 2 services with different ports. For more details, consult xref:running-locally.adoc#multiple_services[Running multiple services].
 
 It is also possible to interact with arbitrary non-Akka services using the `HttpClientProvider`, for such use,
 pass a string with `https://example.com` or `http://example.com` instead of a service name.

docs/src/modules/java/pages/message-brokers.adoc

@@ -0,0 +1,26 @@
+= Message broker integrations
+include::ROOT:partial$include.adoc[]
+
+Akka offers built-in message broker integrations for use with the Akka Consumer and Producer component. These built-in integrations are available for Google Cloud Pub/Sub and hosted Kafka services. For other broker technologies, Java client libraries can be used directly to implement publishing of messages.
+
+== Using built-in integrations
+
+For the built-in technologies, Akka decouples the broker configuration from the implementation of the consumer or producer. The topic name is referenced independently of the broker technology, as demonstrated in xref:consuming-producing.adoc#consume_topic[Consume from a message broker Topic] and xref:consuming-producing.adoc#topic_producing[Producing to a message broker Topic].
+
+All connection details are managed at the Akka project level. For configuration instructions, refer to xref:operations:projects/message-brokers.adoc[Configure message brokers].
+
+The Akka SDK testkit has built-in support for simulating message brokers. See xref:java:consuming-producing.adoc#testing[Testing the Integration] for more details. For running locally with a broker, refer to xref:java:running-locally.adoc#_local_broker_support[running a service with broker support].
+
+== Producing to other broker technologies
+
+Other message broker technologies can be integrated into an Akka service by utilizing their respective client libraries. Additionally, the https://doc.akka.io/libraries/alpakka/current[Akka libraries Alpakka project] provides Akka-native solutions for integrating various services.
+
+We continuously evaluate additional integrations for potential built-in support in Akka. If you have specific requirements, please contact us at mailto:[email protected][].
+
+
+[#_see_also]
+== See also
+
+- xref:operations:projects/message-brokers.adoc[]
+- xref:reference:cli/akka-cli/akka_projects_config.adoc#_see_also[`akka projects config` commands]
+- https://doc.akka.io/libraries/alpakka/current[Akka integrations through Alpakka]

docs/src/modules/java/pages/running-locally.adoc

@@ -105,7 +105,7 @@ For Google PubSub Emulator, use `akka.javasdk.dev-mode.eventing.support=google-p
 
 NOTE: For Kafka, the local Kafka broker is expected to be available on `localhost:9092`. For Google PubSub, the emulator is expected to be available on `localhost:8085`.
 
-
+[#multiple_services]
 == Running multiple services locally
 
 A typical application is composed of one or more services deployed to the same Akka project. When deployed under the same project, two different services can make xref:component-and-service-calls.adoc[calls to each other] or xref:consuming-producing.adoc[subscribe to each other's event streams] by simply using their logical names.

docs/src/modules/operations/nav.adoc

@@ -13,10 +13,10 @@
 **** xref:operations:projects/container-registries.adoc[]
 ***** xref:operations:projects/external-container-registries.adoc[]
 **** xref:operations:projects/message-brokers.adoc[]
-***** xref:operations:projects/broker-aiven.adoc[Aiven for Kafka]
-***** xref:operations:projects/broker-aws-msk.adoc[AWS MSK Kafka]
-***** xref:operations:projects/broker-confluent.adoc[Confluent Cloud]
 ***** xref:operations:projects/broker-google-pubsub.adoc[Google Pub/Sub]
+***** xref:operations:projects/broker-confluent.adoc[Confluent Cloud]
+***** xref:operations:projects/broker-aws-msk.adoc[AWS MSK Kafka]
+***** xref:operations:projects/broker-aiven.adoc[Aiven for Kafka]
 **** xref:operations:projects/secrets.adoc[]
 
 *** xref:operations:services/index.adoc[]
@@ -36,4 +36,4 @@
 *** xref:operations:integrating-cicd/index.adoc[]
 **** xref:operations:integrating-cicd/github-actions.adoc[]
 
-*** xref:operations:operator-best-practices.adoc[]
+*** xref:operations:operator-best-practices.adoc[]

docs/src/modules/operations/pages/projects/broker-aws-msk.adoc

@@ -1,7 +1,7 @@
 = Using AWS MSK as Kafka service
 include::ROOT:partial$include.adoc[]
 
-Akka connects to https://aws.amazon.com/msk/[AWS MSK, window="new"] clusters via TLS, authenticating using SASL (Simple Authentication and Security Layer) SCRAM.
+Akka connects to https://aws.amazon.com/msk/[Amazon MSK, window="new"] clusters via TLS, authenticating using SASL (Simple Authentication and Security Layer) SCRAM.
 
 Prerequisites not covered in detail by this guide:
 

docs/src/modules/operations/pages/projects/message-brokers.adoc

@@ -1,28 +1,28 @@
 = Configure message brokers
 include::ROOT:partial$include.adoc[]
 
-Akka eventing integrates with https://cloud.google.com/pubsub/docs/overview[Google Cloud Pub/Sub, window="new"] and managed Kafka services such as https://www.confluent.io/confluent-cloud[Confluent Cloud, window="new"] and https://aiven.io/kafka[Aiven for Apache Kafka, window="new"] to enable asynchronous messaging.
+Akka eventing integrates with _Google Cloud Pub/Sub_ and managed Kafka services such as _Confluent Cloud_, _Amazon Managed Streaming for Apache Kafka (Amazon MSK)_, and _Aiven for Apache Kafka_ to enable asynchronous messaging and integrations with other systems.
 
-Message brokers are configured on Akka Project level. A project can have one broker configuration, Akka eventing is independent of the broker technology.
+Message brokers are configured at the Akka project level. A project can have one broker configuration. Akka eventing is independent of the broker technology.
 
 == Broker services
 
-- xref:operations:projects/broker-aiven.adoc[Aiven for Apache Kafka]
-- xref:operations:projects/broker-aws-msk.adoc[AWS MSK Kafka]
-- xref:operations:projects/broker-confluent.adoc[Confluent Cloud]
-- xref:operations:projects/broker-google-pubsub.adoc[Google Pub/Sub]
+Follow the detailed steps to configure the desired message broker service for use with your Akka project:
 
-[#_testing]
-== Testing Akka eventing
+- xref:operations:projects/broker-google-pubsub.adoc[Google Pub/Sub]
+- xref:operations:projects/broker-confluent.adoc[Confluent Cloud]
+- xref:operations:projects/broker-aws-msk.adoc[Amazon MSK]
+- xref:operations:projects/broker-aiven.adoc[Aiven for Apache Kafka]
 
-The Java SDK testkit has built-in support to simulate message brokers. See xref:java:consuming-producing.adoc#testing[Testing the Integration].
+We continuously evaluate additional integrations for potential built-in support in Akka. If you have specific requirements, please contact us at mailto:[email protected][].
 
-For running locally with a broker, see xref:java:running-locally.adoc#_local_broker_support[running a service with broker support].
+For running Akka services that integrate with a message broker locally, see xref:java:running-locally.adoc#_local_broker_support[running a service with broker support].
 
 [#_see_also]
-
-
-
 == See also
 
 - xref:reference:cli/akka-cli/akka_projects_config.adoc#_see_also[`akka projects config` commands]
+- https://cloud.google.com/pubsub/docs/overview[Google Cloud Pub/Sub, window="new"]
+- https://www.confluent.io/confluent-cloud[Confluent Cloud, window="new"]
+- https://aws.amazon.com/msk/[Amazon MSK, window="new"]
+- https://aiven.io/kafka[Aiven for Apache Kafka, window="new"]