diff --git a/src/docbkx/ip.xml b/src/docbkx/ip.xml index 74ba55f0fc..a2666ba3e6 100644 --- a/src/docbkx/ip.xml +++ b/src/docbkx/ip.xml @@ -20,32 +20,29 @@ by joining to a multicast address. - 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 + TCP inbound and outbound adapters are provided TcpSendingMessageHandler + sends messages over TCP. TcpReceivingChannelAdapter receives messages over TCP. + If you have been using an earlier 2.0 milestone, note that 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 + An inbound TCP gateway is provided; this allows for simple request/response processing. While the gateway can support any number of connections, each connection can only process serially. The thread - that reads from the socket waits for, and sends, the response before reading again. + that reads from the socket waits for, and sends, the response before reading again. If the connection factory + is configured for single use connections, the connection is closed after the socket times out. - A simple outbound TCP gateway is provided; this allows for simple request/response processing. Each - 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. + An outbound TCP gateway is provided; this allows for simple request/response processing. + If the associated connection factory is configured for single use connections, a new connection is + immediately created for each new request. Otherwise, if the connection is in use, + the calling thread blocks on the connection until either a response is received or an I/O error occurs.
UDP Adapters - - - - - + + Connection factories can be configured with a reference to a + TcpConnectionInterceptorFactoryChain. Interceptors can be used + to add behavior to connections, such as negotiation, security, and other setup. + Further documentation to follow. + For a full reference of the attributes available on connection factories, see the reference at the end of this section. @@ -330,118 +329,31 @@ '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* - 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. - Four standard message formats are provided for this purpose; you can also provide code - for your own custom format. The first of the four 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). These three formats require a byte array or String payload outbound endpoints; inbound - endpoints produce messages with byte array payloads. The fourth format is 'serialized' wherby - standard java serialization is used; payloads must implement Serializable. - For the simple formats, the first (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. The length-header format can also handle binary data. The other two formats can 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; therefore it is not recommened - that these formats be used without some transformation if the data may contain these characters. - - - ]]> - 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. - -
TCP Gateways - The simple inbound TCP gateway SimpleTcpNetInboundGateway - and simple oubound TCP gateway SimpleTcpNetOutboundGateway - use java.net.Socket for communications. Each connection + The inbound TCP gateway TcpInboundGateway + and oubound TCP gateway TcpOutboundGateway + use a server and client connection factory respectively. Each connection can process a single request/response at a time. - The inbound gateway delegates to a subclass of the TcpNetReceivingChannelAdapter - described above, so please read that section for more information. After - constructing a message with the incoming payload and sending + After constructing a message with the incoming payload and sending it to the requestChannel, it waits for a response and sends the payload - from the response message by writing it to the socket, using the same - message format configured for the incoming message. + from the response message by writing it to the connection. - The outbound gateway delegates to a TcpNetSendingMessageHandler - described above, so please read that section for more information. After - sending a message over the socket, the thread waits for a response and - constructs a response message with a byte[] payload The incoming - response is decoded using the same - message format configured for the outgoing message. Communications over - the socket are single-threaded. Users should be aware that only one + After sending a message over the connection, the thread waits for a response and + constructs a response message + Communications over the connections are single-threaded. Users should be aware that only one message can be handled at a time and if another thread attempts to send - a message before the current response has been received, it will block. Only - when the inprocess message receives a response (or times out based on the - socket timeout option) will it proceed. If an error occurs while reading the - response, the socket will be closed, regardless of the close attribute. + a message before the current response has been received, it will block until + any previous requests are complete (or time out). + If, however, the client connection factory is configured for single-use connections + each new request gets its own connection and is processed immediately. - - + + interceptor-factory-chain + Y + Y + + Documentation to be supplied. + - Legacy IP Outbound Channel Adapter Attributes + UDP Outbound Channel Adapter Attributes - - - - + + 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 @@ -684,8 +582,6 @@ 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 @@ -693,8 +589,6 @@ 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 @@ -702,118 +596,42 @@ 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, serialized, 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 NxxSocketWriter, - depending on whether using-nio is false or true. - so-timeout - Y - Y - See java.net.Socket and java.net.DatagramSocket + See java.net.DatagramSocket setSoTimeout() methods for more information. so-send-buffer-size - Y - Y - See java.net.Socket and java.net.DatagramSocket + See 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(). - local-address N @@ -822,13 +640,10 @@ On a multi-homed system, for the UDP adapter, specifies an IP address for the interface to which the socket will be bound for reply messages. For a multicast adapter it is also used to determine which interface - the multicast packets will be sent over. Not applicable to the TCP - adapter. + the multicast packets will be sent over. task-executor - N - Y Specifies a specific Executor to be used for acknowledgment handling. If not supplied, an internal @@ -840,144 +655,75 @@
- Legacy IP Inbound Channel Adapter Attributes + UDP Inbound Channel Adapter Attributes - - - - + + 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. - 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. + Specifies the concurrency. Specifies how many packets can + be handled concurrently. + It only applies if task-executor is not configured. + Defaults to 5. 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. + requirements. receive-buffer-size - Y - Y - For udp, the size of the buffer used to receive DatagramPackets. + 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.For tcp, the size of the - buffer used to reassemble incoming messages. Effectively the maximum - message size that can be received. + 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, serialized, 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 NxxSocketReader, - depending on whether using-nio is false or true. - so-timeout - Y - Y - See java.net.Socket and java.net.DatagramSocket + See 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. @@ -987,32 +733,15 @@ Y Y - See java.net.Socket and java.net.DatagramSocket + See java.net.DatagramSocket setReceiveBufferSize() for more information. - - so-keep-alive - Y - N - true, false - See java.net.Socket. setKeepAlive(). - local-address - Y - Y On a multi-homed system, specifies an IP address for the interface to which the socket will be bound. - - close - Y - N - - If set to true, instructs the adapter to close the socket - after receiving a message. Defaults to false. -
@@ -1036,87 +765,6 @@ The port on which the gateway listens. - - pool-size - - Specifies the number of concurrent connections supported - by the gateway. A thread from the pool is used to handle each socket. - 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. - - - task-executor - - - 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. - - - receive-buffer-size - - The size of the - buffer used to reassemble incoming messages. Effectively the maximum - message size that can be received. - - - message-format - length-header, stx-etx, crlf, serialized, custom - The formatting that the tcp gateway uses for demarcating - incoming requests and formatting responses. Defaults to length-header. - See the discussion above for details about each format. - - - custom-socket- reader-class-name - Subclass of TcpNetSocket- Reader - When message-format is 'custom' the name of the class that - implements the custom format. Must be a subclass of the - TcpNetSocketReader. - - - custom-socket- writer-class-name - Subclass of TcpNetSocket- Writer - When message-format is 'custom' the name of the class that - implements the custom format. Must be a subclass of the - TcpNetSocketWriter. - - - so-timeout - - See java.net.Socket - setSoTimeout() for more information. - - - so-send-buffer-size - - See java.net.Socket - setSendBufferSize() methods for more information. - - - so-receive-buffer- size - - See java.net.Socket - setReceiveBufferSize() for more information. - - - so-keep-alive - true, false - See java.net.Socket. setKeepAlive(). - - - local-address - - On a multi-homed system, specifies an IP address - for the interface to which the socket will be bound. - - - close - - If set to true, instructs the gateway to close the socket - after sending the reply to a message. Defaults to false. - @@ -1140,69 +788,6 @@ The host name or ip address of the destination. - - port - - The port to which the gateway connects. - - - receive-buffer-size - - The size of the - buffer used to reassemble incoming messages. Effectively the maximum - message size that can be received. - - - message-format - length-header, stx-etx, crlf, serialized, custom - The formatting that the tcp gateway uses for formating - requests and demarcating - incoming responses. Defaults to length-header. - See the discussion above for details about each format. - - - custom-socket- reader-class-name - Subclass of TcpNetSocket- Reader - When message-format is 'custom' the name of the class that - implements the custom format. Must be a subclass of the - TcpNetSocketReader. - - - custom-socket- writer-class-name - Subclass of TcpNetSocket- Writer - When message-format is 'custom' the name of the class that - implements the custom format. Must be a subclass of the - TcpNetSocketWriter. - - - so-timeout - - See java.net.Socket - setSoTimeout() for more information. - - - so-send-buffer-size - - See java.net.Socket - setSendBufferSize() methods for more information. - - - so-receive-buffer- size - - See java.net.Socket - setReceiveBufferSize() for more information. - - - so-keep-alive - true, false - See java.net.Socket. setKeepAlive(). - - - close - - If set to true, instructs the adapter to close the socket - after receiving the reply to a message. Defaults to false. -