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.

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.

]]> 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.

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 demarcate 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.

Attribute Name TCP? UDP? Allowed Values Attribute Description protocol Y Y tcp, udp Determines whether the adapter uses TCP or UDP, over IP. host Y Y The host name or ip address of the destination. For multicast udp adapters, the multicast address. port Y Y The port on the destination. multicast N Y true, false Whether or not the udp adapter uses multicast. acknowledge N Y true, false Whether or not a udp adapter requires an acknowledgment from the destination. when enabled, requires setting the following 4 attributes. ack-host N Y When acknowledge is true, indicates the host or ip address to which the acknowledgment should be sent. Usually the current host, but may be different, for example when Network Address Transation (NAT) is being used. ack-port N Y When acknowledge is true, indicates the port to which the acknowledgment should be sent. The adapter listens on this port for acknowledgments. ack-timeout N Y When acknowledge is true, indicates the time in milliseconds that the adapter will wait for an acknowlegment. If an acknowlegment is not received in time, the adapter will throw an exception. min-acks-for- success N Y Defaults to 1. For multicast adapters, you can set this to a larger value, requiring acknowlegments from multiple destinations. check-length N Y true, false Whether or not a udp adapter includes a data length field in the packet sent to the destination. time-to-live N Y For multicast adapters, specifies the time to live attribute for the MulticastSocket; controls the scope of the multicasts. Refer to the Java API documentation for more information. using-nio Y N true, false Whether or not the tcp adapter is using NIO. Refer to the java.nio package for more information. using-direct-buffers Y N true, false When using NIO, whether or not the tcp adapter uses direct buffers. Refer to java.nio.ByteBuffer documentation for more information. message-format Y N length-header, stx-etx, crlf, custom The formatting that the tcp adapter uses so the receiver can demarcate messages. Defaults to length-header. See the discussion above for details about each format. custom-socket- writer-class-name Y N Subclass of TcpNetSocket- Writer or TcpNioSocket- Writer When message-format is 'custom' the name of the class that implements the custom format. Must be a subclass of the TcpNxxSocketWriter, depending on whether using-nio is false or true. so-timeout Y Y See java.net.Socket and java.net.DatagramSocket setSoTimeout() methods for more information. so-send-buffer-size Y Y See java.net.Socket and java.net.DatagramSocket setSendBufferSize() methods for more information. so-receive-buffer- size N Y Used for udp acknowlegment packets. See java.net.DatagramSocket setReceiveBufferSize() methods for more information. so-keep-alive Y N true, false See java.net.Socket. setKeepAlive(). so-linger Y N Sets linger to true with supplied value. See java.net.Socket. setSoLinger(). so-tcp-no-delay Y N true, false See java.net.Socket. setTcpNoDelay(). so-traffic-class Y N See java.net.Socket. setTrafficClass(). Attribute Name TCP? UDP? Allowed Values Attribute Description protocol Y Y tcp, udp Determines whether the adapter uses TCP or UDP, over IP. port Y Y The port on which the adapter listens. multicast N Y true, false Whether or not the udp adapter uses multicast. multicast-address N Y When multicast is true, the multicast address to which the adapter joins. pool-size Y Y Specifies the concurrency. For udp, specifies how many packets can be handled concurrently. For tcp, not using nio, specifies the number of concurrent connections supported by the adapter. For tcp, using nio, specifies the number of tcp fragments that are concurrently reassembled into complete messages. receive-buffer-size N Y For udp, the size of the buffer used to receive DatagramPackets. Usually set to the MTU size. If a smaller buffer is used than the size of the sent packet, truncation can occur. This can be detected by means of the check-length attribute. check-length N Y true, false Whether or not a udp adapter expects a data length field in the packet received. Used to detect packet truncation. using-nio Y N true, false Whether or not the tcp adapter is using NIO. Refer to the java.nio package for more information. using-direct-buffers Y N true, false When using NIO, whether or not the tcp adapter uses direct buffers. Refer to java.nio.ByteBuffer documentation for more information. message-format Y N length-header, stx-etx, crlf, custom The formatting that the tcp adapter uses so the adapter can demarcate messages. Defaults to length-header. See the discussion above for details about each format. custom-socket- reader-class-name Y N Subclass of TcpNetSocket- Reader or TcpNioSocket- Reader When message-format is 'custom' the name of the class that implements the custom format. Must be a subclass of the TcpNxxSocketReader, depending on whether using-nio is false or true. so-timeout Y Y See java.net.Socket and java.net.DatagramSocket setSoTimeout() methods for more information. so-send-buffer-size N Y Used for udp acknowlegment packets. See java.net.DatagramSocket setSendBufferSize() methods for more information. so-receive-buffer- size Y Y See java.net.Socket and java.net.DatagramSocket setReceiveBufferSize() for more information. so-keep-alive Y N true, false See java.net.Socket. setKeepAlive().