GH-3591: Add gateway() section into dsl.adoc (#3593)

* GH-3591: Add `gateway()` section into `dsl.adoc`

Fixes #3591

* Apply review requested changes

Author: artembilan

src/reference/asciidoc/chain.adoc

@@ -130,6 +130,7 @@ You can access them from the `BeanFactory` by using the appropriate bean name, a
 
 TIP: It is useful to provide an explicit `id` attribute on `<chain>` elements to simplify the identification of sub-components in logs and to provide access to them from the `BeanFactory` etc.
 
+[[chain-gateway]]
 ==== Calling a Chain from within a Chain
 
 Sometimes, you need to make a nested call to another chain from within a chain and then come back and continue execution within the original chain.

src/reference/asciidoc/dsl.adoc

@@ -599,6 +599,44 @@ public IntegrationFlow integerFlow() {
 
 Also see <<java-dsl-class-cast>>.
 
+[[java-dsl-gateway]]
+=== Operator gateway()
+
+The `gateway()` operator in an `IntegrationFlow` definition is a special service activator implementation, to call some other endpoint or integration flow via its input channel and wait for reply.
+Technically it plays the same role as a nested `<gateway>` component in a `<chain>` definition (see <<./chain.adoc#chain-gateway,Calling a Chain from within a Chain>>) and allows a flow  to be cleaner and more straightforward.
+Logically, and from business perspective, it is a messaging gateway to allow the distribution and reuse of functionality between different parts of the target integration solution (see <<./gateway.adoc#gateway,Messaging Gateways>>).
+This operator has several overloads for different goals:
+
+- `gateway(String requestChannel)` to send a message to some endpoint's input channel by its name;
+- `gateway(MessageChannel requestChannel)` to send a message to some endpoint's input channel by its direct injection;
+- `gateway(IntegrationFlow flow)` to send a message to the input channel of the provided `IntegrationFlow`.
+
+All of these have a variant with the second `Consumer<GatewayEndpointSpec>` argument to configure the target `GatewayMessageHandler` and respective `AbstractEndpoint`.
+Also the `IntegrationFlow`-based methods allows calling existing `IntegrationFlow` bean or declare the flow as a sub-flow via an in-place lambda for an `IntegrationFlow` functional interface or have it extracted in a `private` method cleaner code style:
+
+====
+[source,java]
+----
+@Bean
+IntegrationFlow someFlow() {
+        return IntegrationFlows
+                .from(...)
+                .gateway(subFlow())
+                .handle(...)
+                .get();
+}
+
+private static IntegrationFlow subFlow() {
+        return f -> f
+                .scatterGather(s -> s.recipientFlow(...),
+                        g -> g.outputProcessor(MessageGroup::getOne))
+}
+----
+====
+
+IMPORTANT: If the downstream flow does not always return a reply, you should set the `requestTimeout` to 0 to prevent hanging the calling thread indefinitely.
+In that case, the flow will end at that point and the thread released for further work.
+
 [[java-dsl-log]]
 === Operator log()