GH-3192: pub-sub DSL for broker-backed channels (#3193)

* GH-3192: pub-sub DSL for broker-backed channels

Fixes https://github.com/spring-projects/spring-integration/issues/3192

* Introduce a `BroadcastCapableChannel` abstract to indicate those `SubscribableChannel`
implementations which can provide a pub-sub functionality
* Implement a `BroadcastCapableChannel` in broker-baked channels with pub-sub option
* Introduce a `BaseIntegrationFlowDefinition.publishSubscribeChannel()` based
on the `BroadcastCapableChannel` and `BroadcastPublishSubscribeSpec` to let to
configure sub-flow subscribers in fluent manner

* * Add some JavaDocs and document new feature

* * Show the channel bean definition in the doc
* Fix typo

src/reference/asciidoc/dsl.adoc

@@ -742,6 +742,40 @@ public IntegrationFlow subscribersFlow() {
 You can achieve the same result with separate `IntegrationFlow` `@Bean` definitions, but we hope you find the sub-flow style of logic composition useful.
 We find that it results in shorter (and so more readable) code.
 
+Starting with version 5.3, a `BroadcastCapableChannel`-based `publishSubscribeChannel()` implementation is provided to configure sub-flow subscribers on broker-backed message channels.
+For example we now can configure several subscribers as sub-flows on the `Jms.publishSubscribeChannel()`:
+
+====
+[source,java]
+----
+@Bean
+public BroadcastCapableChannel jmsPublishSubscribeChannel() {
+    return Jms.publishSubscribeChannel(jmsConnectionFactory())
+                .destination("pubsub")
+                .get();
+}
+
+@Bean
+public IntegrationFlow pubSubFlow() {
+    return f -> f
+            .publishSubscribeChannel(jmsPublishSubscribeChannel(),
+                    pubsub -> pubsub
+                            .subscribe(subFlow -> subFlow
+                                .channel(c -> c.queue("jmsPubSubBridgeChannel1")))
+                            .subscribe(subFlow -> subFlow
+                                .channel(c -> c.queue("jmsPubSubBridgeChannel2"))));
+}
+
+@Bean
+public BroadcastCapableChannel jmsPublishSubscribeChannel(ConnectionFactory jmsConnectionFactory) {
+    return (BroadcastCapableChannel) Jms.publishSubscribeChannel(jmsConnectionFactory)
+            .destination("pubsub")
+            .get();
+}
+
+----
+====
+
 A similar `publish-subscribe` sub-flow composition provides the `.routeToRecipients()` method.
 
 Another example is using `.discardFlow()` instead of `.discardChannel()` on the `.filter()` method.

src/reference/asciidoc/whats-new.adoc

@@ -53,6 +53,10 @@ See <<./graph.adoc#integration-graph,Integration Graph>> for more information.
 In the aggregator, when the `MessageGroupProcessor` returns a `Message`, the `MessageBuilder.popSequenceDetails()` is performed on the output message if the `sequenceDetails` matches the header in the first message of the group.
 See <<./aggregator.adoc#aggregator-api,Aggregator Programming Model>> for more information.
 
+A new `publishSubscribeChannel()` operator, based on the `BroadcastCapableChannel` and `BroadcastPublishSubscribeSpec`, was added into Java DSL.
+This fluent API has its advantage when we configure sub-flows as pub-sub subscribers for broker-backed channels like `SubscribableJmsChannel`, `SubscribableRedisChannel` etc.
+See <<./dsl.adoc#java-dsl-subflows,Sub-flows support>> for more information.
+
 [[x5.3-amqp]]
 === AMQP Changes