diff --git a/src/docbkx/ip.xml b/src/docbkx/ip.xml index 2693af65c0..94a0cf5ca9 100644 --- a/src/docbkx/ip.xml +++ b/src/docbkx/ip.xml @@ -20,11 +20,10 @@ 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. + TCP inbound and outbound adapters are provided TcptSendingMessageHandler + sends messages over TCP. TcpNetReceivingChannelAdapter receives messages over TCP. + The adapters are no longer configured with connection options directly; instead, they are given + a reference to a connection factory. See below. A simple inbound TCP gateway is provided; this allows for simple request/response processing. While @@ -36,6 +35,11 @@ request is processed serially. The calling thread blocks on the socket until either a response is received or an I/O error occurs. Requests are single-threaded over the socket. + + The gateways have not yet been converted to use the stand-alone tcp connection factories. If you are + using the gateways, you should configure them as before (legacy documentation remains below). + The gateways will be converted shortly. +
UDP Adapters @@ -125,9 +129,204 @@ A basic multicast inbound udp channel adapter.
+
+ TCP Connection Factories + + For TCP, the configuration of the underlying connection is provided using a + Connection Factory. Two types of connection factory are provided; a + client connection factory and a server connection factory. Client connection + factories are used to establish outgoing connections; Server connection factories + listen for incoming connections. + + + A client connection factory is used + by an outbound channel adapter but a reference to a client connection factory + can also be provided to an inbound channel adapter and that adapter will receive + any incoming messages received on connections created by the outbound adapter. + + + A server connection factory is used by an inbound channel adapter (in fact + the connection factory will not function without one). A reference to a server + connection factory can also be provided to an outbound adapter; that adapter + can then be used to send replies to incoming messages to the same connection. + Reply messages will only be routed to the connection if the reply contains + the header $ip_connection_id that was inserted into the original message by + the connection factory. + This is the extent of message correlation performed when sharing connection + factories between inbound and outbound adapters. Such sharing allows for + asynchronous two-way communication over TCP. Only payload information is + transferred using TCP; therefore any message correlation must be performed + by downstream components such as aggregators or other endpoints. + + + A maximum of one adapter of each type may be given a reference to a connection + factory. + + + Connection factories using java.net.Socket and + java.nio.channel.SocketChannel are provided. + + + ]]> + A simple server connection factory that uses java.net.Socket + connections. + + + ]]> + A simple server connection factory that uses java.nio.channel.SocketChannel + connections. + + + ]]> + A client connection factory that uses java.net.Socket + connections and creates a new connection for each message. + + + ]]> + A client connection factory that uses java.nio.channel.Socket + connections and creates a new connection for each message. + + + 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. + Connection factories are configured to use converters to convert between the message + payload and the bits that are sent over TCP. This is accomplished by providing an + input converter and output converter for inbound and outbound messages respectively. + Four standard converters are provided; the first is ByteArrayCrlfConverter, + which can convert a String or byte array to a stream of bytes followed by carriage + return and linefeed characters (\r\n). This is the default converter and can be used with + telnet as a client, for example. The second is is ByteArrayStxEtxConverter, + which can convert a String or byte array to a stream of bytes preceded by an STX (0x02) and + followed by an ETX (0x03). The third is ByteArrayLengthHeaderConverter, + which can convert a String or byte array to a stream of bytes preceded by a 4 byte binary + length in network byte order. Each of these converts an input stream containing the + corresponding format to a byte array payload. The fourth converter is + JavaSerializationConverter which can be used to convert any + Serializable objects. We expect to provide other serialization technologies but you may also + supply your own by implementing the InputStreamingConverter and + OutputStreamingConverter interfaces. If you do not wish to use + the default converters, you must supply input-converter and + output-converter attributes on the connection factory: + + + + + ]]> + A server connection factory that uses java.net.Socket + connections and uses Java serialization on the wire. + + + + Normally, with shared connections, one would expect the the same wire protocol + to be used for both inbound and outbound messages; however, the configuration + allows them to be different. Note, however that if you only specify one converter + the other direction will use the default converter. + + + + For a full reference of the attributes available on connection factories, see the + reference at the end of this section. + +
TCP Adapters + TCP inbound and outbound channel adapters that utilize the above connection + factories are provided. These adapters have just 2 attributes + connection-factory and channel. + The channel attribute specifies the channel on which messages arrive at an + outbound adapter and on which messages are placed by an inbound adapter. + + + + + + + + + + + + + + + + + + + + + + + ]]> + In this configuration, messages arriving in channel 'input' + are serialized over connections created by 'client' received + at the server and placed on channel 'loop'. Since 'loop' is + the input channel for 'outboundServer' the message is simply + looped back over the same connection and received by + 'inboundClient' and deposited in channel 'replies'. + +
+
+ TCP Adapters - Legacy - These Adapters Will be Removed Before 2.0 GA + + These adapters have been replaced with the adapters above please migrate + to the new configuration; these adapters will not be available in GA 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* @@ -253,10 +452,165 @@
- IP Endpoint Attributes + IP Configuration Attributes + + Connection Factory Attributes + + + + + + + + + + Attribute Name + Client? + Server? + Allowed Values + Attribute Description + + + + + type + Y + Y + client, server + Determines whether the connection factory is a client or server. + + + host + Y + N + + The host name or ip address of the destination. + + + port + Y + Y + + The port. + + + using-nio + Y + Y + true, false + Whether or not the tcp adapter is using NIO. Refer to the java.nio + package for more information.i Default false. + + + 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. Must be false if using-nio is false. + + + so-timeout + Y + Y + + See java.net.Socket + setSoTimeout() methods for more information. + + + so-send-buffer-size + Y + Y + + See java.net.Socket + setSendBufferSize() methods for more information. + + + so-receive-buffer- size + Y + Y + + See java.net.Socket + setReceiveBufferSize() methods for more information. + + + so-keep-alive + Y + Y + true, false + See java.net.Socket. setKeepAlive(). + + + so-linger + Y + Y + + Sets linger to true with supplied value. + See java.net.Socket. setSoLinger(). + + + so-tcp-no-delay + Y + Y + true, false + See java.net.Socket. setTcpNoDelay(). + + + so-traffic-class + Y + Y + + See java.net.Socket. setTrafficClass(). + + + local-address + N + Y + + On a multi-homed system, specifies an IP address + for the interface to which the socket will be bound. + + + + task-executor + Y + Y + + + Specifies a specific Executor to be used for socket handling. If not supplied, an internal + pooled executor will be used. Needed on some platforms that require the use of specific + task executors such as a WorkManagerTaskExecutor. See pool-size for thread + requirements, depending on other options. + + + single-use + Y + Y + true, false + Specifies whether a connection can be used for multiple messages. + If true, a new connection will be used for each message. + + + pool-size + Y + Y + + Specifies the concurrency. + 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. + It only applies in this sense if task-executor is not configured. + However, pool-size is also used for the server socket backlog, + regardless of whether an external task executor is used. Defaults to 5. + + + +
- IP Outbound Channel Adapter Attributes + Legacy IP Outbound Channel Adapter Attributes @@ -479,7 +833,7 @@
- IP Inbound Channel Adapter Attributes + Legacy IP Inbound Channel Adapter Attributes