SOL-49780: SCSt README Cleanup (#127)

* Expand table of contents to 3 levels
* Rewrite overview to be more clear
* Try to make it more apparent that Solace session configuration is handled by the Solace Java Spring Boot starter (a completely different project)
* Remove references to obsolete `prefix` consumer/producer config options. The `prefix` option was removed in `3.0.0`.

README.md

@@ -29,7 +29,7 @@ Please consult the [Spring Cloud Compatibility Table](./solace-spring-cloud-bom/
 ### Solace Spring Cloud Projects
 
 These are the projects contained within this repository:
-* [Solace Spring Cloud Stream Starter](./solace-spring-cloud-starters/solace-spring-cloud-stream-starter)
+* [Spring Cloud Stream Binder for Solace PubSub+](./solace-spring-cloud-starters/solace-spring-cloud-stream-starter)
 * [Solace Spring Cloud Connector](./solace-spring-cloud-connector)
 
 ## Building Locally

solace-spring-cloud-starters/solace-spring-cloud-stream-starter/README.adoc

@@ -1,6 +1,7 @@
 = Spring Cloud Stream Binder for Solace PubSub+
 :revnumber: 3.2.1
 :toc: preamble
+:toclevels: 3
 :icons: font
 :scst-version: 3.2.2
 
@@ -19,21 +20,26 @@ An implementation of Spring's Cloud Stream Binder for integrating with Solace Pu
 
 The Solace implementation of the Spring Cloud Stream Binder maps the following concepts from Spring to Solace:
 
-* Destinations to topic subscriptions (Source apps always send messages to a topic)
+* Destinations to topics/subscriptions
+** Producer bindings always sends messages to topics
 * Consumer groups to durable queues
+** A consumer group's queue is subscribed to its destination subscription (default)
+** Consumer bindings always receives messages from queues
 * Anonymous consumer groups to temporary queues (When no group is specified; used for SCS Publish-Subscribe Model)
 
-And internally, each consumer group queue is subscribed to at least their destination topic. So a typical message flow would then appear as follows:
+In Solace, the above setup is called topic-to-queue mapping. So a typical message flow would then appear as follows:
 
 . Producer bindings publish messages to their destination topics
-. Consumer group queues receive the messages published to their destination topic
-. Consumers of a particular consumer group consume messages from their group in a round-robin fashion (by default)
+. Each consumer groups' queue receives the messages published to their destination topic
+. The PubSub+ broker distributes messages in a round-robin fashion to each consumer binding for a particular consumer group
++
+NOTE: Round-robin distribution only occurs if the consumer group's queue is configured for non-exclusive access. If the queue has exclusive access, then only one consumer will receive messages.
 
-Note that partitioning is not yet supported by this version of the binder.
+NOTE: Partitioning is not yet supported by this version of the binder.
 
-Note that since the Binder always consumes from queues it is currently required that Assured Delivery be enabled on the Solace PubSub+ Message VPN being used (Assured Delivery is automatically enabled if using Solace Cloud.)
+IMPORTANT: Since consumer bindings always consumes from queues it is required that Assured Delivery is enabled on the Solace PubSub+ Message VPN being used (Assured Delivery is automatically enabled if using Solace Cloud). Additionally, the client username's client profile must be allowed to send and receive guaranteed messages.
 
-Also, it will be assumed that you have a basic understanding of the Spring Cloud Stream project. If not, then please refer to https://docs.spring.io/spring-cloud-stream/docs/{scst-version}/reference/html/[Spring's documentation]. For the sake of brevity, this document will solely focus on discussing components unique to Solace.
+For the sake of brevity, it will be assumed that you have a basic understanding of the Spring Cloud Stream project. If not, then please refer to https://docs.spring.io/spring-cloud-stream/docs/{scst-version}/reference/html/[Spring's documentation]. This document will solely focus on discussing components unique to Solace.
 
 == Spring Cloud Stream Binder
 
@@ -120,29 +126,43 @@ spring:
  solace-broker:
  type: solace
  environment:
- solace:
+ solace: # <1>
  java:
  host: tcp://localhost:55555
  msgVpn: default
  clientUsername: default
  clientPassword: default
  connectRetries: -1
  reconnectRetries: -1
+# apiProperties:
+# ssl_trust_store: <path_to_trust_store>
+# ssl_trust_store_password: <trust_store_password>
+# ssl_validate_certificate: true
 ----
-
-Notice that the latter half of this configuration actually originates from the https://github.com/SolaceProducts/solace-spring-boot/tree/master/solace-spring-boot-starters/solace-java-spring-boot-starter#updating-your-application-properties[JCSMP Spring Boot Auto-Configuration project].
+<1> The latter half of this configuration where the Solace session is configured actually originates from the https://github.com/SolaceProducts/solace-spring-boot/tree/master/solace-spring-boot-starters/solace-java-spring-boot-starter#updating-your-application-properties[JCSMP Spring Boot Auto-Configuration project]. See <<Solace Session Properties>> for more info.
 
 == Configuration Options
 
 === Solace Binder Configuration Options
 
 Configuration of the Solace Spring Cloud Stream Binder is done through https://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-external-config.html[Spring Boot's externalized configuration]. This is where users can control the binder's configuration options as well as the Solace Java API properties.
 
-=== Inherited Configuration Options
+For general binder configuration options and properties, refer to the https://docs.spring.io/spring-cloud-stream/docs/{scst-version}/reference/html/spring-cloud-stream.html#_configuration_options[Spring Cloud Stream Reference Documentation].
 
-As for auto-configuration-related options required for auto-connecting to Solace message brokers, refer to the https://github.com/SolaceProducts/solace-spring-boot/tree/master/solace-spring-boot-starters/solace-java-spring-boot-starter#configure-the-application-to-use-your-solace-pubsub-service-credentials[JCSMP Spring Boot Auto-Configuration documentation].
+==== Solace Session Properties
 
-For general binder configuration options and properties, refer to the https://docs.spring.io/spring-cloud-stream/docs/{scst-version}/reference/html/spring-cloud-stream.html#_configuration_options[Spring Cloud Stream Reference Documentation].
+The binder's Solace session is configurable using properties prefixed by `solace.java` or `spring.cloud.stream.binders.<binder-name>.environment.solace.java`.
+
+IMPORTANT: This binder leverages the JCSMP Spring Boot Auto-Configuration project to configure its session. See the https://github.com/SolaceProducts/solace-spring-boot/tree/master/solace-spring-boot-starters/solace-java-spring-boot-starter#configure-the-application-to-use-your-solace-pubsub-service-credentials[JCSMP Spring Boot Auto-Configuration documentation] for more info on how to configure these properties.
+
+See <<Creating a Simple Solace Binding>> for a simple example of how to configure a session for this binder.
+
+[TIP]
+====
+Additional session properties not available under the usual `solace.java` prefix can be set using `solace.java.apiProperties.<property>`, where `<property>` is the name of a https://docs.solace.com/API-Developer-Online-Ref-Documentation/java/com/solacesystems/jcsmp/JCSMPProperties.html[JCSMPProperties constant] (e.g. `ssl_trust_store`).
+
+See https://github.com/SolaceProducts/solace-spring-boot/tree/master/solace-spring-boot-starters/solace-java-spring-boot-starter#updating-your-application-properties[JCSMP Spring Boot Auto-Configuration documentation] for more info about `solace.java.apiProperties`.
+====
 
 ==== Solace Consumer Properties
 
@@ -249,10 +269,10 @@ Default: `null`
 
 queueAdditionalSubscriptions::
 An array of additional topic subscriptions to be applied on the consumer group queue. +
-These subscriptions may also contain wildcards. +
-The `prefix` property is not applied on these subscriptions.
+These subscriptions may also contain wildcards.
 +
-Default: `String[0]`
+Default: `String[0]` +
+See: <<Overview>> for more info on how this binder uses topic-to-queue mapping to implement Spring Cloud Streams consumer groups.
 
 polledConsumerWaitTimeInMillis::
 Maximum wait time for polled consumers to receive a message from their consumer group queue. +
@@ -487,10 +507,10 @@ Default: `null`
 
 queueAdditionalSubscriptions::
 A mapping of required consumer groups to arrays of additional topic subscriptions to be applied on each consumer group's queue. +
-These subscriptions may also contain wildcards. +
-The `prefix` property is not applied on these subscriptions.
+These subscriptions may also contain wildcards.
 +
-Default: Empty `Map&lt;String,String[]&gt;`
+Default: Empty `Map&lt;String,String[]&gt;` +
+See: <<Overview>> for more info on how this binder uses topic-to-queue mapping to implement Spring Cloud Streams consumer groups.
 
 === Solace Message Headers
 
@@ -927,31 +947,25 @@ If asynchronously acknowledging messages, then if these messages aren’t acknow
 This property can be configured for dynamically created queues by using https://docs.solace.com/Configuring-and-Managing/Configuring-Endpoint-Templates.htm#Configur[queue templates]. However note that as per https://docs.solace.com/PubSub-Basics/Endpoints.htm#Which[our documentation], anonymous consumer group queues (i.e. temporary queues) will not match a queue template’s name filter. Only the queue template defined in the client profile’s "Copy Settings From Queue Template" setting will apply to those.
 ====
 
-== Message Target Destination
+== Dynamic Producer Destinations
 
 Spring Cloud Stream has a reserved message header called `scst_targetDestination` (retrievable via `BinderHeaders.TARGET_DESTINATION`), which allows for messages to be redirected from their bindings' configured destination to the target destination specified by this header.
 
-For this binder's implementation of this header, the target destination defines the _exact_ Solace topic to which a message will be sent. i.e. No post-processing is done for this header (e.g. `prefix` is not applied).
-
-If you want to apply a destination post-processing step – lets say the `prefix` for example, you will need to directly apply that to the header itself:
+For this binder's implementation of this header, the target destination defines the _exact_ Solace topic to which a message will be sent. i.e. No post-processing is done for this header.
 
 [source,java]
 ----
 public class MyMessageBuilder {
- @Value("${spring.cloud.stream.solace.bindings.<bindingName>.producer.prefix}") // <1>
- String prefix;
-
  public Message<String> buildMeAMessage() {
  return MessageBuilder.withPayload("payload")
- .setHeader(BinderHeaders.TARGET_DESTINATION, prefix + "new-target-destination") // <2>
+ .setHeader(BinderHeaders.TARGET_DESTINATION, "some-dynamic-destination") // <1>
  .build();
  }
 }
 ----
-<1> Retrieve your binding's configured prefix.
-<2> Apply the prefix to the target destination header.
+<1> This message will be sent to the `some-dynamic-destination` topic, ignoring the producer's configured destination
 
-Also, this header is cleared by the message's producer before it is sent off to the message broker. So you should attach the target destination to your message payload if you want to get that information on the consumer-side.
+NOTE: This header is cleared by the message's producer before it is sent off to the message broker. So you should attach the target destination to your message payload if you want to get that information on the consumer-side.
 
 == Failed Consumer Message Error Handling
 

solace-spring-cloud-stream-binder/solace-spring-cloud-stream-binder-core/src/main/java/com/solace/spring/cloud/stream/binder/properties/SolaceConsumerProperties.java

@@ -43,7 +43,6 @@ public class SolaceConsumerProperties extends SolaceCommonProperties {
  /**
  * An array of additional topic subscriptions to be applied on the consumer group queue.
  * These subscriptions may also contain wildcards.
- * The prefix property is not applied on these subscriptions.
  */
  private String[] queueAdditionalSubscriptions = new String[0];
  /**

solace-spring-cloud-stream-binder/solace-spring-cloud-stream-binder-core/src/main/java/com/solace/spring/cloud/stream/binder/properties/SolaceProducerProperties.java

@@ -32,7 +32,6 @@ public class SolaceProducerProperties extends SolaceCommonProperties {
  /**
  * A mapping of required consumer groups to arrays of additional topic subscriptions to be applied on each consumer group’s queue.
  * These subscriptions may also contain wildcards.
- * The prefix property is not applied on these subscriptions.
  */
  private Map<String,String[]> queueAdditionalSubscriptions = new HashMap<>();
  /**