INT-1552 IP Doc Polishing
This commit is contained in:
Gary Russell
@@ -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.
|
||||
<tip>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.</tip>
|
||||
<tip>This is the extent of message correlation performed when sharing connection
|
||||
<tip>
|
||||
<para>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.</para></tip>
|
||||
<tip>
|
||||
<para>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.</tip>
|
||||
by downstream components such as aggregators or other endpoints.
|
||||
For more information refer to
|
||||
<xref linkend="ip-correlation">TCP Message Correlationn</xref></para></tip>
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
@@ -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.
|
||||
</para>
|
||||
<para>
|
||||
<programlisting language="xml"><![CDATA[
|
||||
@@ -444,6 +448,94 @@
|
||||
A simple oubound TCP gateway.
|
||||
</para>
|
||||
</section>
|
||||
<section id="ip-correlation">
|
||||
<title>TCP Message Correlation</title>
|
||||
<section>
|
||||
<title>Overview</title>
|
||||
<para>
|
||||
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).
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Gateways</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
Therefore, for high-volume messages, consider using a collaborating pair of
|
||||
channel adapters. However, you will need to provide collaboration logic.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Collaborating Outbound and Inbound Channel Adapters</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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 <classname>DefaultSerializer/Deserializer</classname> which use java
|
||||
serialization, or a custom serializer and deserializer.
|
||||
The <classname>ByteArray*Serializer</classname> options
|
||||
mentioned in <xref linkend="connection-factories">Connection Factories</xref>,
|
||||
including the default <classname>ByteArrayCrLfSerializer</classname>,
|
||||
do not support such payloads,
|
||||
unless the transformed payload is a <classname>String</classname> or
|
||||
<classname>byte[]</classname>,
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
<section id="ip-endpoint-reference">
|
||||
<title>IP Configuration Attributes</title>
|
||||
<para>
|
||||
@@ -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.</entry>
|
||||
</row>
|
||||
<row>
|
||||
@@ -830,6 +922,70 @@
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<table id="tcp-ib-adapter-attributes">
|
||||
<title>TCP Inbound Channel Adapter Attributes</title>
|
||||
<tgroup cols="3">
|
||||
<colspec align="left" />
|
||||
<colspec colnum="1" colname="col1" colwidth="1*"/>
|
||||
<colspec colnum="2" colname="col2" colwidth="1*"/>
|
||||
<colspec colnum="3" colname="col3" colwidth="3*"/>
|
||||
<thead>
|
||||
<row>
|
||||
<entry align="center">Attribute Name</entry>
|
||||
<entry align="left">Allowed Values</entry>
|
||||
<entry align="center">Attribute Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>channel</entry>
|
||||
<entry></entry>
|
||||
<entry>The channel to which inbound messages will be sent.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>connection-factory</entry>
|
||||
<entry></entry>
|
||||
<entry>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.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<table id="tcp-ob-adapter-attributes">
|
||||
<title>TCP Outbound Channel Adapter Attributes</title>
|
||||
<tgroup cols="3">
|
||||
<colspec align="left" />
|
||||
<colspec colnum="1" colname="col1" colwidth="1*"/>
|
||||
<colspec colnum="2" colname="col2" colwidth="1*"/>
|
||||
<colspec colnum="3" colname="col3" colwidth="3*"/>
|
||||
<thead>
|
||||
<row>
|
||||
<entry align="center">Attribute Name</entry>
|
||||
<entry align="left">Allowed Values</entry>
|
||||
<entry align="center">Attribute Description</entry>
|
||||
</row>
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>channel</entry>
|
||||
<entry></entry>
|
||||
<entry>The channel on which outbound messages arrive.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>connection-factory</entry>
|
||||
<entry></entry>
|
||||
<entry>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. </entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
<table id="tcp-ib-gateway-attributes">
|
||||
<title>TCP Inbound Gateway Attributes</title>
|
||||
<tgroup cols="3">
|
||||
@@ -846,9 +1002,26 @@
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>port</entry>
|
||||
<entry>connection-factory</entry>
|
||||
<entry></entry>
|
||||
<entry>The port on which the gateway listens.</entry>
|
||||
<entry>The connection factory must be of type server. </entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>request-channel</entry>
|
||||
<entry></entry>
|
||||
<entry>The channel to which incoming messages will be sent.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>reply-channel</entry>
|
||||
<entry></entry>
|
||||
<entry>The channel on which reply messages may arrive. Usually replies will
|
||||
arrive on a temporary reply channel added to the inbound message
|
||||
header</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>reply-timeout</entry>
|
||||
<entry></entry>
|
||||
<entry>The time in milliseconds for which the gateway will wait for a reply.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
@@ -869,9 +1042,32 @@
|
||||
</thead>
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>host</entry>
|
||||
<entry>connection-factory</entry>
|
||||
<entry></entry>
|
||||
<entry>The host name or ip address of the destination.</entry>
|
||||
<entry>The connection factory must be of type client. </entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>request-channel</entry>
|
||||
<entry></entry>
|
||||
<entry>The channel on which outgoing messages will arrive.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>reply-channel</entry>
|
||||
<entry></entry>
|
||||
<entry>Optional. The channel to which reply messages may be sent if the
|
||||
original outbound message did not contain a reply channel header.
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>reply-timeout</entry>
|
||||
<entry></entry>
|
||||
<entry>The time in milliseconds for which the gateway will wait for a reply.</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry>request-timeout</entry>
|
||||
<entry></entry>
|
||||
<entry>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.</entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
|
||||
Reference in New Issue
Block a user