Spring/spring-integration
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

INT-1269 Docs for Refactored Tcp Adapters

Browse Source
This commit is contained in:
Gary Russell
2010-07-27 01:27:37 +00:00
parent 2eea14ebd6
commit d2d6fc191d
1 changed files with 362 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

370
src/docbkx/ip.xml
View File

@@ -20,11 +20,10 @@
by joining to a multicast address.
</para>
<para>
Two flavors each of TCP inbound and outbound adapters are provided <classname>TcpNetSendingMessageHandler</classname>
and <classname>TcpNioSendingMessageHandler</classname> send messages over TCP. They are functionally equivalent,
but use different underlying technology for socket communication. Similarly, <classname>TcpNetReceivingChannelAdapter</classname>
and <classname>TcpNioReceivingChannelAdapter</classname> 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 <classname>TcptSendingMessageHandler</classname>
sends messages over TCP. <classname>TcpNetReceivingChannelAdapter</classname> receives messages over TCP.
<tip>The adapters are no longer configured with connection options directly; instead, they are given
a reference to a connection factory. See below.</tip>
</para>
<para>
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.
</para>
<para>
<tip>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.</tip>
</para>
</section>
<section id="udp-adapters">
<title>UDP Adapters</title>
@@ -125,9 +129,204 @@
A basic multicast inbound udp channel adapter.
</para>
</section>
<section id="connection-factories">
<title>TCP Connection Factories</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
<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
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>
</para>
<para>
A maximum of one adapter of each type may be given a reference to a connection
factory.
</para>
<para>
Connection factories using <classname>java.net.Socket</classname> and
<classname>java.nio.channel.SocketChannel</classname> are provided.
</para>
<para>
<programlisting language="xml"><![CDATA[
<ip:tcp-connection-factory id="server"
type="server"
port="1234"
/>]]></programlisting>
A simple server connection factory that uses <classname>java.net.Socket</classname>
connections.
</para>
<para>
<programlisting language="xml"><![CDATA[
<ip:tcp-connection-factory id="server"
type="server"
port="1234"
using-nio="true"
/>]]></programlisting>
A simple server connection factory that uses <classname>java.nio.channel.SocketChannel</classname>
connections.
</para>
<para>
<programlisting language="xml"><![CDATA[
<ip:tcp-connection-factory id="client"
type="client"
host="localhost"
port="1234"
single-use="true"
so-timeout="10000"
/>]]></programlisting>
A client connection factory that uses <classname>java.net.Socket</classname>
connections and creates a new connection for each message.
</para>
<para>
<programlisting language="xml"><![CDATA[
<ip:tcp-connection-factory id="client"
type="client"
host="localhost"
port="1234"
single-use="true"
so-timeout="10000"
using-nio=true
/>]]></programlisting>
A client connection factory that uses <classname>java.nio.channel.Socket</classname>
connections and creates a new connection for each message.
</para>
<para>
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 <classname>ByteArrayCrlfConverter</classname>,
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 <classname>ByteArrayStxEtxConverter</classname>,
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 <classname>ByteArrayLengthHeaderConverter</classname>,
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
<classname>JavaSerializationConverter</classname> 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 <classname>InputStreamingConverter</classname> and
<classname>OutputStreamingConverter</classname> interfaces. If you do not wish to use
the default converters, you must supply <classname>input-converter</classname> and
<classname>output-converter</classname> attributes on the connection factory:
</para>
<para>
<programlisting language="xml"><![CDATA[
<bean id="serial"
class="org.springframework.commons.serializer.JavaSerializationConverter" />
<ip:tcp-connection-factory id="server"
type="server"
port="1234"
input-converter="serial"
output-converter="serial"
/>]]></programlisting>
A server connection factory that uses <classname>java.net.Socket</classname>
connections and uses Java serialization on the wire.
</para>
<para>
<tip>
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.
</tip>
</para>
<para>
For a full reference of the attributes available on connection factories, see the
reference at the end of this section.
</para>
</section>
<section id="tcp-adapters">
<title>TCP Adapters</title>
<para>
TCP inbound and outbound channel adapters that utilize the above connection
factories are provided. These adapters have just 2 attributes
<classname>connection-factory</classname> and <classname>channel</classname>.
The channel attribute specifies the channel on which messages arrive at an
outbound adapter and on which messages are placed by an inbound adapter.
</para>
<para>
<programlisting language="xml"><![CDATA[
<bean id="serializer" class="org.springframework.commons.serializer.JavaSerializationConverter" />
<int-ip:tcp-connection-factory id="server"
type="server"
port="1234"
input-converter="serializer"
output-converter="serializer"
using-nio="true"
single-use="true"
/>
<int-ip:tcp-connection-factory id="client"
type="client"
host="localhost"
port="#{server.port}"
single-use="true"
so-timeout="10000"
input-converter="serializer"
output-converter="serializer"
/>
<int:channel id="input" />
<int:channel id="replies">
<int:queue/>
</int:channel>
<int-ip:tcp-outbound-channel-adapter id="outboundClient"
channel="input"
connection-factory="client"/>
<int-ip:tcp-inbound-channel-adapter id="inboundClient"
channel="replies"
connection-factory="client"/>
<int-ip:tcp-inbound-channel-adapter id="inboundServer"
channel="loop"
connection-factory="server"/>
<int-ip:tcp-outbound-channel-adapter id="outboundServer"
channel="loop"
connection-factory="server"/>
<int:channel id="loop" />]]></programlisting>
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'.
</para>
</section>
<section id="legacy-tcp-adapters">
<title>TCP Adapters - Legacy - These Adapters Will be Removed Before 2.0 GA</title>
<para>
<tip>These adapters have been replaced with the adapters above please migrate
to the new configuration; these adapters will not be available in GA</tip>
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 @@
</para>
</section>
<section id="ip-endpoint-reference">
<title>IP Endpoint Attributes</title>
<title>IP Configuration Attributes</title>
<para>
<table id="connection-factory-attributes">
<title>Connection Factory Attributes</title>
<tgroup cols="5">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="0.3*" align="center"/>
<colspec colnum="3" colname="col3" colwidth="0.3*" align="center"/>
<colspec colnum="4" colname="col4" colwidth="1*"/>
<colspec colnum="5" colname="col5" colwidth="2*"/>
<thead>
<row>
<entry align="center">Attribute Name</entry>
<entry align="center">Client?</entry>
<entry align="center">Server?</entry>
<entry align="center">Allowed Values</entry>
<entry align="center">Attribute Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>type</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>client, server</entry>
<entry>Determines whether the connection factory is a client or server.</entry>
</row>
<row>
<entry>host</entry>
<entry>Y</entry>
<entry>N</entry>
<entry></entry>
<entry>The host name or ip address of the destination.</entry>
</row>
<row>
<entry>port</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>The port.</entry>
</row>
<row>
<entry>using-nio</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Whether or not the tcp adapter is using NIO. Refer to the java.nio
package for more information.i Default false.</entry>
</row>
<row>
<entry>using-direct-buffers</entry>
<entry>Y</entry>
<entry>N</entry>
<entry>true, false</entry>
<entry>When using NIO, whether or not the tcp adapter uses direct buffers.
Refer to <classname>java.nio.ByteBuffer</classname> documentation for
more information. Must be false if using-nio is false. </entry>
</row>
<row>
<entry>so-timeout</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setSoTimeout() methods for more information.</entry>
</row>
<row>
<entry>so-send-buffer-size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setSendBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-receive-buffer- size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket</classname>
setReceiveBufferSize() methods for more information.</entry>
</row>
<row>
<entry>so-keep-alive</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setKeepAlive()</classname>.</entry>
</row>
<row>
<entry>so-linger</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>Sets linger to true with supplied value.
See <classname>java.net.Socket. setSoLinger()</classname>.</entry>
</row>
<row>
<entry>so-tcp-no-delay</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>See <classname>java.net.Socket. setTcpNoDelay()</classname>.</entry>
</row>
<row>
<entry>so-traffic-class</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>See <classname>java.net.Socket. setTrafficClass()</classname>.</entry>
</row>
<row>
<entry>local-address</entry>
<entry>N</entry>
<entry>Y</entry>
<entry></entry>
<entry>On a multi-homed system, specifies an IP address
for the interface to which the socket will be bound.
</entry>
</row>
<row>
<entry>task-executor</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>
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.</entry>
</row>
<row>
<entry>single-use</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry>true, false</entry>
<entry>Specifies whether a connection can be used for multiple messages.
If true, a new connection will be used for each message.</entry>
</row>
<row>
<entry>pool-size</entry>
<entry>Y</entry>
<entry>Y</entry>
<entry></entry>
<entry>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.</entry>
</row>
</tbody>
</tgroup>
</table>
<table id="ip-ob-adapter-attributes">
<title>IP Outbound Channel Adapter Attributes</title>
<title>Legacy IP Outbound Channel Adapter Attributes</title>
<tgroup cols="5">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
@@ -479,7 +833,7 @@
</tgroup>
</table>
<table id="ip-ib-adapter-attributes">
<title>IP Inbound Channel Adapter Attributes</title>
<title>Legacy IP Inbound Channel Adapter Attributes</title>
<tgroup cols="5">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>