GH-3155: Add support for Java DSL extensions (#3167)

* GH-3155: Add support for Java DSL extensions

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

Provide an `IntegrationFlowExtension` for possible custom EI-operators
in the target project use-cases.

* * Move `IntegrationFlowExtension` tests ot its own test class
* Make all the `IntegrationComponentSpec` ctors as `protected` for possible custom extensions
* Make some `BaseIntegrationFlowDefinition` methods and properties as `protected` to get them
access from the `IntegrationFlowExtension` implementations
* Document the feature

* * Fix language and typos in docs

* * Add `protected` to one more `GatewayEndpointSpec` ctor
* Add JavaDocs to `GatewayEndpointSpec` methods

* * Add `protected` to one more `JmsPollableMessageChannelSpec` ctor

src/reference/asciidoc/dsl.adoc

@@ -1202,3 +1202,63 @@ That `errorRecovererFlow` can be used as follows:
 private Function<String, String> errorRecovererFlowGateway;
 ----
 ====
+
+[[java-dsl-extensions]]
+=== DSL Extensions
+
+Starting with version 5.3, an `IntegrationFlowExtension` has been introduced to allow extension of the existing Java DSL with custom or composed EIP-operators.
+All that is needed is an extension of this class that provides methods which can be used in the `IntegrationFlow` bean definitions.
+The extension class can also be used for custom `IntegrationComponentSpec` configuration; for example, missed or default options can be implemented in the existing `IntegrationComponentSpec` extension.
+The sample below demonstrates a composite custom operator and usage of an `AggregatorSpec` extension for a default custom `outputProcessor`:
+
+====
+[source,java]
+----
+public class CustomIntegrationFlowDefinition
+        extends IntegrationFlowExtension<CustomIntegrationFlowDefinition> {
+
+    public CustomIntegrationFlowDefinition upperCaseAfterSplit() {
+        return split()
+                .transform("payload.toUpperCase()");
+    }
+
+    public CustomIntegrationFlowDefinition customAggregate(Consumer<CustomAggregatorSpec> aggregator) {
+        return register(new CustomAggregatorSpec(), aggregator);
+    }
+
+}
+
+public class CustomAggregatorSpec extends AggregatorSpec {
+
+    CustomAggregatorSpec() {
+        outputProcessor(group ->
+                group.getMessages()
+                        .stream()
+                        .map(Message::getPayload)
+                        .map(String.class::cast)
+                        .collect(Collectors.joining(", ")));
+    }
+
+}
+----
+====
+
+For a method chain flow the new DSL operator in these extensions must return the extension class.
+This way a target `IntegrationFlow` definition will work with new and existing DSL operators:
+
+====
+[source,java]
+----
+@Bean
+public IntegrationFlow customFlowDefinition() {
+    return
+            new CustomIntegrationFlowDefinition()
+                    .log()
+                    .upperCaseAfterSplit()
+                    .channel("innerChannel")
+                    .customAggregate(customAggregatorSpec ->
+                            customAggregatorSpec.expireGroupsUponCompletion(true))
+                    .logAndReply();
+}
+----
+====

src/reference/asciidoc/whats-new.adoc

@@ -27,18 +27,20 @@ See its JavaDocs and <<./graph.adoc#integration-graph,Integration Graph>> for mo
 The `ReactiveMessageHandler` is now natively supported in the framework.
 See <<./reactive-streams.adoc/reactive-message-handler,ReactiveMessageHandler>> for more information.
 
+[[x5.3-java-dsl-extensions]]
+==== Java DSL Extensions
+
+A new `IntegrationFlowExtension` API has been introduced to allow extension of the existing Java DSL with custom or composed EIP-operators.
+This also can be used to introduce customizers for any out-of-the-box `IntegrationComponentSpec` extensions.
+See <<./dsl.adoc/java-dsl-extensions,DSL Extensions>> for more information.
+
+
 [[x5.3-mongodb-reactive-channel-adapters]]
 ==== MongoDB Reactive Channel Adapters
 
 `spring-integration-mongodb` module now provides channel adapter implementations for Reactive MongoDB driver support in Spring Data.
 See <<./mongodb.adoc#mongodb-reactive-channel-adapters,MongoDB Reactive Channel Adapters>> for more information.
 
-[[x5.3-AbstractCorrelatingMessageHandler]]
-==== Aggregator Changes
-
-If the `MessageGroupProcessor` returns a `Message`, the `MessageBuilder.popSequenceDetails()` is performed on the output message if the `sequenceDetails` matches with first message of group.
-See <<./aggregator.adoc#aggregator-api,Aggregator Programming Model>> for more information.
-
 [[x5.3-general]]
 === General Changes
 
@@ -48,6 +50,9 @@ See <<./gateway.adoc/gateway-calling-default-methods,Invoking `default` Methods>
 Internal components (such as `_org.springframework.integration.errorLogger`) now have a shortened name when they are represented in the integration graph.
 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.
+
 [[x5.3-amqp]]
 === AMQP Changes