diff --git a/spring-integration-reference/src/ip.xml b/spring-integration-reference/src/ip.xml index 2a8067d55b..496f59e340 100644 --- a/spring-integration-reference/src/ip.xml +++ b/spring-integration-reference/src/ip.xml @@ -2,12 +2,189 @@ TCP and UDP Support - + + Spring Integration provides Channel Adapters for receiving and sending messages over internet protocols. Both UDP + (User Datagram Protocol) + and TCP (Transmission Control Protocol) adapters are provided. Each adapter provides for one-way communication + over the underlying protocol. Gateways providing two-way communication may be considered in a future release. +
Introduction - TODO + Two flavors each of UDP inbound and outbound adapters are provided UnicastSendingMessageHandler + sends a datagram packet to a single destination. UnicastReceivingChannelAdapter receives + incoming datagram packets. MulticastSendingMessageHandler sends (broadcasts) datagram packets to + a multicast address. MulticastReceivingChannelAdapter receives incoming datagram packets + by joining to a multicast address. + + + Two flavors each of TCP inbound and outbound adapters are provided TcpNetSendingMessageHandler + and TcpNioSendingMessageHandler send messages over TCP. They are functionally equivalent, + but use different underlying technology for socket communication. Similarly, TcpNetReceivingChannelAdapter + and TcpNioReceivingChannelAdapter are the equivalent inbound channel adapters. + The choice of which to use in what circumstances is described below.
- +
+ UDP Adapters + + ]]> + A simple UDP outbound channel adapter. + + When setting multicast to true, provide the multicast address in the host + attribute. + + + + UDP is an efficient, but unreliable protocol. Two attributes are added to improve reliability. When check-length is + set to true, the adapter precedes the message data with a length field (4 bytes in network byte order). This enables + the receiving side to verify the length of the packet received. If a receiving system uses a buffer that is too + short the contain the packet, the packet can be truncated. The length header provides a mechanism to detect this. + + + ]]> + An outbound channel adapter that adds length checking to the datagram packets. + + The recipient of the packet must also be configured to expect a length to precede the + actual data. For a Spring Integration UDP inbound channel adapter, set its + check-length attribute. + + + + The second reliability improvement allows an application-level acknowledgment protocol to be used. The receiver + must send an acknowledgment to the sender within a specified time. + + + ]]> + An outbound channel adapter that adds length checking to the datagram packets and waits for an acknowledgment. + + Setting acknowledge to true implies the recipient of the packet can interpret the header added to the packet + containing acknowledgment data (host and port). Most likely, the recipient will be a Spring Integration inbound + channel adapter. + + + When multicast is true, an additional attribute min-acks-for-success specifies + how many acknowledgments must be received within the ack-timeout. + + + + For even more reliable networking, TCP can be used. + + + ]]> + A basic unicast inbound udp channel adapter. + + + ]]> + A basic multicast inbound udp channel adapter. + +
+
+ TCP Adapters + + Two versions of TCP inbound and outbound channel adapters are provided; these adapters + use either java.net.Socket IO, or java.nio.channels.SocketChannel IO. The choice of which + to use depends on the application. The TcpNet* adapters use java.net.Socket and the TcpNio* + adapters use java.nio.channels.ChannelSocket. It is not anticipated that much difference in + performance, if any, would exist between these technologies on the outbound side. This is + because each outbound adapter sends data over only one socket. On the receiving side + however, consideration should be given to the number of connections. For the + TcpNetReceivingChannelAdapter a thread is dedicated to receiving + data on each connected socket; the pool size must therefore be set large enough to handle + the expected number of connections. For the TcpNioReceivingChannelAdapter + threads are used on an as-needed basis and it is likely that many fewer threads would be + needed. If a small number of connections is expected, we expect that the the TcpNetReceivingChannelAdapter + will give the best performance. For large number of connections, the TcpNioReceivingChannelAdapter will + likely give the best performance. In addition, the TcpNioReceivingChannelAdapter provides an + attribute using-direct-buffers which attempts to use direct buffers. See + java.nio.ByteBuffer for more information about direct buffers. + + It is not expected that direct buffers will offer much, if any, performance difference. You + should experiment with the use of TcpNxx* adapters, and direct buffers when using TcpNio* + adapters to determine the best performance in your environment. + + + + TCP is a streaming protocol; this means that some structure has to be provided to data + transported over TCP, so the receiver can delimit the data into discrete messages. + Three standard message formats are provided for this purpose; you can also provide code + for your own custom format. The first of the three standard formats is length-header, in which case a 4 byte + length header precedes the data; this is the default. The second is stx-etx in which the message + data is preceded by an STX (0x02) character and terminated with an ETX (0x03) character. + The third is crlf in which the message is terminated with a carriage return and line feed + (\r\n). The first format (the default) is likely to be the most performant. This is because + we can determine exactly how many bytes to read to obtain the complete message. The other + two formats require examining each byte to determine if the end of the message has been + received. This length-header format can also handle binary data. The other two formats an only handle + text data (specifcally, data that does not contain characters 0x02 and 0x03 for stx-etx and + 0x0d and 0x0a for crlf. This limitation can be avoided by appropriate character escaping techniques + in the application layer. No such escaping is provided by the adapters. + + + ]]> + A basic outbound tcp channel adapter. This adapter uses java.nio.channels.SocketChannel. + To use a java.net.Socket, set using-nio to false and + using-direct-buffers is not relevant. + +
+ + ]]> + A basic inbound tcp channel adapter. This adapter uses java.nio.channels.SocketChannel. + To use a java.net.Socket, set using-nio to false and + using-direct-buffers is not relevant. + \ No newline at end of file