diff --git a/docs/src/reference/docbook/ip.xml b/docs/src/reference/docbook/ip.xml index 9f3dd98307..d8a668888b 100644 --- a/docs/src/reference/docbook/ip.xml +++ b/docs/src/reference/docbook/ip.xml @@ -140,14 +140,18 @@ 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 + + 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. + by downstream components such as aggregators or other endpoints. + For more information refer to + TCP Message Correlationn A maximum of one adapter of each type may be given a reference to a connection @@ -406,7 +410,7 @@ can process a single request/response at a time. - The intbound gateway, after constructing a message with the incoming payload and sending + The intbound gateway, after constructing a message with the incoming payload and sending it to the requestChannel, waits for a response and sends the payload from the response message by writing it to the connection. @@ -416,9 +420,9 @@ 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 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. + 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. +
+ TCP Message Correlation +
+ Overview + + One goal of the IP Endpoints is to provide communication with systems other + than another Spring Integration application. For this reason, only + message payloads are sent + and received. No message correlation is provided by the framework, + except when using the gateways, or collaborating channel adapters on the + server side. In the paragraphs below we discuss the various + correlation techniques available to applications. In most cases, this + requires specific application-level correlation of messages, even when + message payloads contain some natural correlation data (such as an order + number). + +
+
+ Gateways + + The gateways will automatically correlate messages. However, an outbound + gateway should only be used for relatively low-volume use. + When the connection + factory is configured for 'single-use="false"', a single shared connection is + used for all message pairs, and only one message can be processed at a time. + A new message will have to wait until the reply to the previous message has + been received. + When a connection + factory is configured for 'single-use="true"' connections, the above + restriction does not apply because each message pair is + carried over a separate connection. While this may give higher throughput + than a shared connection environment, it comes with the overhead of opening + and closing a new connection for each message pair. + + + Therefore, for high-volume messages, consider using a collaborating pair of + channel adapters. However, you will need to provide collaboration logic. + +
+
+ Collaborating Outbound and Inbound Channel Adapters + + To achieve high-volume throughput (avoiding the pitfalls of using gateways + as mentioned above) you may consider configuring a pair of collaborating + outbound and inbound channel adapters. On the server side, message + correlation is automatically handled by the adapters because the inbound + adapter adds a header allowing the outbound adapter to determine which + connection to use to send the reply message. On the client side, however, + the application will have to provide its own correlation logic. This can + be done in a number of ways. + + + If the message payload has some natural correlation data, such as a + transaction id or an order number, AND there is no need to retain any + information (such as a reply channel header) from the original outbound message, + the correlation is simple and would done at the application level in any case. + + + If the message payload has some natural correlation data, such as a + transaction id or an order number, but there is a need to retain some + information (such as a reply channel header) from the original outbound message, + you may need to retain a copy of the original outbound message (perhaps + by using a publish-subscribe channel) and use an aggregator to recombine + the necessary data. + + + For either of the previous two paragraphs, if the payload has no natural + correlation data, you may need to provide a transformer upstream of the + outbound channel adapter to enhance the payload with such data. Such a + transformer may transform the original payload to a new object containing + both the original payload and some subset of the message headers. Of course, + live objects (such as reply channels) from the headers can not be + included in the transformed payload. + + + If such a strategy is chosen you will need to ensure the connection factory + has an appropriate serializer/deserializer pair to handle such a payload, + such as the DefaultSerializer/Deserializer which use java + serialization, or a custom serializer and deserializer. + The ByteArray*Serializer options + mentioned in Connection Factories, + including the default ByteArrayCrLfSerializer, + do not support such payloads, + unless the transformed payload is a String or + byte[], + +
+
IP Configuration Attributes @@ -611,7 +703,7 @@ 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, + However, pool-size is also used for the server socket backlog, regardless of whether an external task executor is used. Defaults to 5. @@ -830,6 +922,70 @@ + + TCP Inbound Channel Adapter Attributes + + + + + + + + Attribute Name + Allowed Values + Attribute Description + + + + + channel + + The channel to which inbound messages will be sent. + + + connection-factory + + If the connection factory has a type 'server', the factory is 'owned' + by this adapter. If it has a type 'client', it is 'owned' by an + outbound channel adapter and this adapter will receive any + incoming messages on the connection created by the + outbound adapter. + + + +
+ + TCP Outbound Channel Adapter Attributes + + + + + + + + Attribute Name + Allowed Values + Attribute Description + + + + + channel + + The channel on which outbound messages arrive. + + + connection-factory + + If the connection factory has a type 'client', the factory is + 'owned' by this adapter. If it has a type 'server', it is 'owned' + by an inbound channel adapter and this adapter will attempt + to correlate messages to the connection on which an + original inbound message was received. + + + +
TCP Inbound Gateway Attributes @@ -846,9 +1002,26 @@ - port + connection-factory - The port on which the gateway listens. + The connection factory must be of type server. + + + request-channel + + The channel to which incoming messages will be sent. + + + reply-channel + + The channel on which reply messages may arrive. Usually replies will + arrive on a temporary reply channel added to the inbound message + header + + + reply-timeout + + The time in milliseconds for which the gateway will wait for a reply. @@ -869,9 +1042,32 @@ - host + connection-factory - The host name or ip address of the destination. + The connection factory must be of type client. + + + request-channel + + The channel on which outgoing messages will arrive. + + + reply-channel + + Optional. The channel to which reply messages may be sent if the + original outbound message did not contain a reply channel header. + + + + reply-timeout + + The time in milliseconds for which the gateway will wait for a reply. + + + request-timeout + + If a single-use connection factory is not being used, The time in milliseconds + for which the gateway will wait to get access to the shared connection.