From f223343d0eed9d23a0891214d00d3d656d9b7940 Mon Sep 17 00:00:00 2001
From: Gary Russell <grussell@pivotal.io>
Date: Tue, 26 Jan 2021 14:37:43 -0500
Subject: [PATCH] GH-3477: Add DSL Docs for TCP Components

Resolves https://github.com/spring-projects/spring-integration/issues/3477

**cherry-pick to 5.4.x**
---
 src/reference/asciidoc/ip.adoc | 78 ++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/src/reference/asciidoc/ip.adoc b/src/reference/asciidoc/ip.adoc
index a0d78011ef..9a8083b66e 100644
--- a/src/reference/asciidoc/ip.adoc
+++ b/src/reference/asciidoc/ip.adoc
@@ -381,6 +381,8 @@ The following example shows a client connection factory that uses `java.net.Sock
 
 Starting with version 5.2, the client connection factories support the property `connectTimeout`, specified in seconds, which defaults to 60.
 
+Also see <<ip-annotation>> and <<ip-dsl>>.
+
 [[tcp-codecs]]
 ==== Message Demarcation (Serializers and Deserializers)
 
@@ -496,6 +498,8 @@ NOTE: You can also modify the attributes of sockets and socket factories.
 See <<ssl-tls>> for more information.
 As noted there, such modifications are possible whether or not SSL is being used.
 
+Also see <<ip-annotation>> and <<ip-dsl>>.
+
 ==== Custom Serializers and Deserializers
 
 If your data is not in a format supported by one of the standard deserializers, you can implement your own; you can also implement a custom serializer.
@@ -815,6 +819,8 @@ The following example shows how to define client and server TCP connection facto
 ----
 ====
 
+Also see <<ip-annotation>> and <<ip-dsl>>.
+
 In the preceding configuration, messages arriving in the `input` channel are serialized over connections created by `client` connection factory, received at the server, and placed on the `loop` channel.
 Since `loop` is the input channel for `outboundServer`, the message is looped back over the same connection, received by `inboundClient`, and deposited in the `replies` channel.
 Java serialization is used on the wire.
@@ -923,6 +929,8 @@ To support this on the server side, you can now register multiple `TcpSender` s
 Gateways and Channel Adapters automatically register themselves.
 When sending unsolicited messages from the server, you must add the appropriate `IpHeaders.CONNECTION_ID` to the messages sent.
 
+Also see <<ip-annotation>> and <<ip-dsl>>.
+
 [[ip-correlation]]
 === TCP Message Correlation
 
@@ -2247,3 +2255,73 @@ In this scenario, the `@ServiceActivator` configures the endpoint, according to
 
 <8> The server-side connection factory.
 ====
+
+[[ip-dsl]]
+=== Using the Java DSL for TCP Components
+
+DSL support for TCP components includes specs for adapters and gateways, the `Tcp` class with factory methods to create connection factory beans, and the `TcpCodecs` class with factory methods to create serializers and deserializers.
+Refer to their javadocs for more information.
+
+Here are some examples of using the DSL to configure flows using the DSL.
+
+.Server Adapter Flow
+====
+[source, java]
+----
+@Bean
+public IntegrationFlow server() {
+    return IntegrationFlows.from(Tcp.inboundAdapter(Tcp.netServer(1234)
+                            .deserializer(TcpCodecs.lengthHeader1())
+                            .backlog(30))
+                        .errorChannel("tcpIn.errorChannel")
+                        .id("tcpIn"))
+            .transform(Transformers.objectToString())
+            .channel("tcpInbound")
+            .get();
+}
+----
+====
+
+.Client Adapter Flow
+====
+[source, java]
+----
+@Bean
+public IntegrationFlow client() {
+    return f -> f.handle(Tcp.outboundAdapter(Tcp.nioClient("localhost", 1234)
+                        .serializer(TcpCodecs.lengthHeader1())));
+}
+----
+====
+
+.Server Gateway Flow
+====
+[source, java]
+----
+@Bean
+public IntegrationFlow server() {
+    return IntegrationFlows.from(Tcp.inboundGateway(Tcp.netServer(1234)
+                            .deserializer(TcpCodecs.lengthHeader1())
+                            .serializer(TcpCodecs.lengthHeader1())
+                            .backlog(30))
+                        .errorChannel("tcpIn.errorChannel")
+                        .id("tcpIn"))
+            .transform(Transformers.objectToString())
+            .channel("tcpInbound")
+            .get();
+}
+----
+====
+
+.Client Gateway Flow
+====
+[source, java]
+----
+@Bean
+public IntegrationFlow client() {
+    return f -> f.handle(Tcp.outboundGateway(Tcp.nioClient("localhost", 1234)
+                        .deserializer(TcpCodecs.lengthHeader1())
+                        .serializer(TcpCodecs.lengthHeader1())));
+}
+----
+====