1104 lines
49 KiB
XML
1104 lines
49 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ip"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>TCP and UDP Support</title>
|
|
<para>
|
|
Spring Integration provides Channel Adapters for receiving and sending messages over internet protocols. Both UDP
|
|
(User Datagram Protocol)
|
|
and TCP (Transmission Control Protocol) adapters are provided. Each adapter provides for one-way communication
|
|
over the underlying protocol.
|
|
In addition, simple inbound and outbound tcp gateways are provided. These are used when two-way communication is
|
|
needed.
|
|
</para>
|
|
<section id="ip-intro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Two flavors each of UDP inbound and outbound channel adapters are provided <classname>UnicastSendingMessageHandler</classname>
|
|
sends a datagram packet to a single destination. <classname>UnicastReceivingChannelAdapter</classname> receives
|
|
incoming datagram packets. <classname>MulticastSendingMessageHandler</classname> sends (broadcasts) datagram packets to
|
|
a multicast address. <classname>MulticastReceivingChannelAdapter</classname> receives incoming datagram packets
|
|
by joining to a multicast address.
|
|
</para>
|
|
<para>
|
|
TCP inbound and outbound channel adapters are provided <classname>TcpSendingMessageHandler</classname>
|
|
sends messages over TCP. <classname>TcpReceivingChannelAdapter</classname> receives messages over TCP.
|
|
</para>
|
|
<para>
|
|
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. If the connection factory
|
|
is configured for single use connections, the connection is closed after the socket times out.
|
|
</para>
|
|
<para>
|
|
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 a timeout
|
|
or I/O error occurs.
|
|
</para>
|
|
<para>
|
|
The TCP and UDP inbound channel adapters, and the TCP inbound gateway, support the "error-channel" attribute.
|
|
This provides the same basic functionality as described in <xref linkend="gateway-proxy"/>.
|
|
</para>
|
|
</section>
|
|
<section id="udp-adapters">
|
|
<title>UDP Adapters</title>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[ <ip:udp-outbound-channel-adapter id="udpOut"
|
|
host="somehost"
|
|
port="11111"
|
|
multicast="false"
|
|
channel="exampleChannel" />]]></programlisting>
|
|
A simple UDP outbound channel adapter.
|
|
<tip>
|
|
When setting multicast to true, provide the multicast address in the host
|
|
attribute.
|
|
</tip>
|
|
</para>
|
|
<para>
|
|
UDP is an efficient, but unreliable protocol. Two attributes are added to improve reliability. When check-length is
|
|
set to true, the adapter precedes the message data with a length field (4 bytes in network byte order). This enables
|
|
the receiving side to verify the length of the packet received. If a receiving system uses a buffer that is too
|
|
short the contain the packet, the packet can be truncated. The length header provides a mechanism to detect this.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[ <ip:udp-outbound-channel-adapter id="udpOut"
|
|
host="somehost"
|
|
port="11111"
|
|
multicast="false"
|
|
check-length="true"
|
|
channel="exampleChannel" />]]></programlisting>
|
|
An outbound channel adapter that adds length checking to the datagram packets.
|
|
<tip>
|
|
The recipient of the packet must also be configured to expect a length to precede the
|
|
actual data. For a Spring Integration UDP inbound channel adapter, set its
|
|
<classname>check-length</classname> attribute.
|
|
</tip>
|
|
</para>
|
|
<para>
|
|
The second reliability improvement allows an application-level acknowledgment protocol to be used. The receiver
|
|
must send an acknowledgment to the sender within a specified time.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[ <ip:udp-outbound-channel-adapter id="udpOut"
|
|
host="somehost"
|
|
port="11111"
|
|
multicast="false"
|
|
check-length="true"
|
|
acknowledge="true"
|
|
ack-host="thishost"
|
|
ack-port="22222"
|
|
ack-timeout="10000"
|
|
channel="exampleChannel" />]]></programlisting>
|
|
An outbound channel adapter that adds length checking to the datagram packets and waits for an acknowledgment.
|
|
<tip>
|
|
Setting acknowledge to true implies the recipient of the packet can interpret the header added to the packet
|
|
containing acknowledgment data (host and port). Most likely, the recipient will be a Spring Integration inbound
|
|
channel adapter.
|
|
</tip>
|
|
<tip>
|
|
When multicast is true, an additional attribute min-acks-for-success specifies
|
|
how many acknowledgments must be received within the ack-timeout.
|
|
</tip>
|
|
</para>
|
|
<para>
|
|
For even more reliable networking, TCP can be used.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[ <ip:udp-inbound-channel-adapter id="udpReceiver"
|
|
channel="udpOutChannel"
|
|
port="11111"
|
|
receive-buffer-size="500"
|
|
multicast="false"
|
|
check-length="true" />]]></programlisting>
|
|
A basic unicast inbound udp channel adapter.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[ <ip:udp-inbound-channel-adapter id="udpReceiver"
|
|
channel="udpOutChannel"
|
|
port="11111"
|
|
receive-buffer-size="500"
|
|
multicast="true"
|
|
multicast-address="225.6.7.8"
|
|
check-length="true" />]]></programlisting>
|
|
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 or gateway (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>
|
|
<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.
|
|
For more information refer to
|
|
<xref linkend="ip-correlation">TCP Message Correlation</xref></para></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 (de)serializers to convert between the message
|
|
payload and the bits that are sent over TCP. This is accomplished by providing a
|
|
deserializer and serializer for inbound and outbound messages respectively.
|
|
Four standard (de)serializers are provided; the first is <classname>ByteArrayCrlfSerializer</classname>,
|
|
which can convert a byte array to a stream of bytes followed by carriage
|
|
return and linefeed characters (\r\n). This is the default (de)serializer and can be used with
|
|
telnet as a client, for example. The second is is <classname>ByteArrayStxEtxSerializer</classname>,
|
|
which can convert a byte array to a stream of bytes preceded by an STX (0x02) and
|
|
followed by an ETX (0x03). The third is <classname>ByteArrayLengthHeaderSerializer</classname>,
|
|
which can convert a byte array to a stream of bytes preceded by a 4 byte binary
|
|
length in network byte order. Each of these is a subclass of
|
|
<classname>AbstractByteArraySerializer</classname> which implements both
|
|
<classname>org.springframework.core.serializer.Serializer</classname> and
|
|
<classname>org.springframework.core.serializer.Deserializer</classname>.
|
|
For backwards compatibility, connections using any subclass of
|
|
<classname>AbstractByteArraySerializer</classname> for serialization
|
|
will also accept a String which will be converted to a byte array first.
|
|
Each of these (de)serializers converts an input stream containing the
|
|
corresponding format to a byte array payload. The fourth standard serializer is
|
|
<classname>org.springframework.core.serializer.DefaultSerializer</classname> which can be
|
|
used to convert Serializable objects using java serialization.
|
|
<classname>org.springframework.core.serializer.DefaultDeserializer</classname> is provided for
|
|
inbound deserialization of streams containing Serializable objects.
|
|
To implement a custom (de)serializer pair, implement the
|
|
<classname>org.springframework.core.serializer.Deserializer</classname> and
|
|
<classname>org.springframework.core.serializer.Serializer</classname> interfaces. If you do not wish to use
|
|
the default (de)serializer (<classname>ByteArrayCrLfSerializer</classname>), you must supply
|
|
<classname>serializer</classname> and
|
|
<classname>deserializer</classname> attributes on the connection factory (example below).
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<bean id="javaSerializer"
|
|
class="org.springframework.core.serializer.DefaultSerializer" />
|
|
<bean id="javaDeserializer"
|
|
class="org.springframework.core.serializer.DefaultDeserializer" />
|
|
|
|
<ip:tcp-connection-factory id="server"
|
|
type="server"
|
|
port="1234"
|
|
deserializer="JavaDeserializer"
|
|
serializer="javaSerializer"
|
|
/>]]></programlisting>
|
|
A server connection factory that uses <classname>java.net.Socket</classname>
|
|
connections and uses Java serialization on the wire.
|
|
</para>
|
|
<para>
|
|
For full details of the attributes available on connection factories, see the
|
|
reference at the end of this section.
|
|
</para>
|
|
</section>
|
|
<section id="ip-interceptors">
|
|
<title>Tcp Connection Interceptors</title>
|
|
<para>
|
|
Connection factories can be configured with a reference to a
|
|
<classname>TcpConnectionInterceptorFactoryChain</classname>. Interceptors can be used
|
|
to add behavior to connections, such as negotiation, security, and other setup.
|
|
No interceptors are currently provided by the framework but, for an example,
|
|
see the <classname>InterceptedSharedConnectionTests</classname> in the source
|
|
repository.
|
|
</para>
|
|
<para>
|
|
The <classname>HelloWorldInterceptor</classname> used in the test case works as follows:
|
|
</para>
|
|
<para>
|
|
When configured with a client connection factory,
|
|
when the first message is sent over a connection that is intercepted, the interceptor
|
|
sends 'Hello' over the connection, and expects to receive 'world!'. When that occurs,
|
|
the negotiation is complete and the original message is sent; further messages
|
|
that use the same connection are sent without any additional negotiation.
|
|
</para>
|
|
<para>
|
|
When configured with a server connection factory, the interceptor requires the first
|
|
message to be 'Hello' and, if it is, returns 'world!'. Otherwise it throws an exception causing
|
|
the connection to be closed.
|
|
</para>
|
|
<para>
|
|
All <classname>TcpConnection</classname> methods are intercepted.
|
|
Interceptor instances are created for each connection by an interceptor factory.
|
|
If an interceptor is stateful, the factory should create a new instance for each connection.
|
|
Interceptor
|
|
factories are added to the configuration of an interceptor factory chain, which is provided
|
|
to a connection factory using the <classname>interceptor-factory</classname> attribute.
|
|
Interceptors must implement the <classname>TcpConnectionInterceptor</classname> interface;
|
|
factories
|
|
must implement the <classname>TcpConnectionInterceptorFactory</classname> interface. A
|
|
convenience class <classname>AbstractTcpConnectionInterceptor</classname> is provided
|
|
with passthrough methods; by extending this class, you only need to implement those
|
|
methods you wish to intercept.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[<bean id="helloWorldInterceptorFactory"
|
|
class="org.springframework.integration.ip.tcp.connection.TcpConnectionInterceptorFactoryChain">
|
|
<property name="interceptors">
|
|
<array>
|
|
<bean class="org.springframework.integration.ip.tcp.connection.HelloWorldInterceptorFactory"/>
|
|
</array>
|
|
</property>
|
|
</bean>
|
|
|
|
<int-ip:tcp-connection-factory id="server"
|
|
type="server"
|
|
port="12345"
|
|
using-nio="true"
|
|
single-use="true"
|
|
interceptor-factory-chain="helloWorldInterceptorFactory"
|
|
/>
|
|
|
|
<int-ip:tcp-connection-factory id="client"
|
|
type="client"
|
|
host="localhost"
|
|
port="12345"
|
|
single-use="true"
|
|
so-timeout="100000"
|
|
using-nio="true"
|
|
interceptor-factory-chain="helloWorldInterceptorFactory"
|
|
/>]]></programlisting>
|
|
Configuring a connection interceptor factory chain.
|
|
</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.
|
|
The connection-factory attribute indicates which connection factory is to be used to
|
|
manage connections for the adapter. While both inbound and outbound adapters
|
|
can share a connection factory, server connection factories are always 'owned'
|
|
by an inbound adapter; client connection factories are always 'owned' by an
|
|
outbound adapter. One, and only one, adapter of each type may get a reference
|
|
to a connection factory.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<bean id="javaSerializer"
|
|
class="org.springframework.core.serializer.DefaultSerializer" />
|
|
<bean id="javaDeserializer"
|
|
class="org.springframework.core.serializer.DefaultDeserializer" />
|
|
|
|
<int-ip:tcp-connection-factory id="server"
|
|
type="server"
|
|
port="1234"
|
|
deserializer="javaDeserializer"
|
|
serializer="javaSerializer"
|
|
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"
|
|
deserializer="javaDeserializer"
|
|
serializer="javaSerializer"
|
|
/>
|
|
|
|
<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'. Java
|
|
serialization is used on the wire.
|
|
</para>
|
|
</section>
|
|
<section id="tcp-gateways">
|
|
<title>TCP Gateways</title>
|
|
<para>
|
|
The inbound TCP gateway <classname>TcpInboundGateway</classname>
|
|
and outbound TCP gateway <classname>TcpOutboundGateway</classname>
|
|
use a server and client connection factory respectively. Each connection
|
|
can process a single request/response at a time.
|
|
</para>
|
|
<para>
|
|
The inbound 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>
|
|
<para>
|
|
The outbound gateway, after sending a message over the connection, waits for a response and
|
|
constructs a response message and puts in on the reply channel.
|
|
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.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<ip:tcp-inbound-gateway id="inGateway"
|
|
request-channel="tcpChannel"
|
|
reply-channel="replyChannel"
|
|
connection-factory="cfServer"
|
|
reply-timeout="10000"
|
|
/>]]></programlisting>
|
|
A simple inbound TCP gateway; if a connection factory configured with the default
|
|
(de)serializer is used, messages will be \r\n delimited data and the gateway can be
|
|
used by a simple client such as telnet.
|
|
</para>
|
|
<para>
|
|
<programlisting language="xml"><![CDATA[
|
|
<ip:tcp-outbound-gateway id="outGateway"
|
|
request-channel="tcpChannel"
|
|
reply-channel="replyChannel"
|
|
connection-factory="cfClient"
|
|
request-timeout="10000"
|
|
reply-timeout="10000"
|
|
/>]]></programlisting>
|
|
A simple outbound 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 a single shared connection
|
|
to be used for all message pairs ('single-use="false"'),
|
|
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 each new message to use a new connection
|
|
('single-use="true"'), the above restriction does not apply.
|
|
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>
|
|
<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.4*" align="center"/>
|
|
<colspec colnum="3" colname="col3" colwidth="0.4*" 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>serializer</entry>
|
|
<entry>Y</entry>
|
|
<entry>Y</entry>
|
|
<entry></entry>
|
|
<entry>An implementation of <classname>Serializer</classname> used to serialize
|
|
the payload. Defaults to <classname>ByteArrayCrLfSerializer</classname></entry>
|
|
</row>
|
|
<row>
|
|
<entry>deserializer</entry>
|
|
<entry>Y</entry>
|
|
<entry>Y</entry>
|
|
<entry></entry>
|
|
<entry>An implementation of <classname>Deserializer</classname> used to deserialize
|
|
the payload. Defaults to <classname>ByteArrayCrLfSerializer</classname></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. 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. 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>
|
|
<row>
|
|
<entry>interceptor-factory-chain</entry>
|
|
<entry>Y</entry>
|
|
<entry>Y</entry>
|
|
<entry></entry>
|
|
<entry>Documentation to be supplied.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table id="ip-ib-adapter-attributes">
|
|
<title>UDP Inbound Channel Adapter Attributes</title>
|
|
<tgroup cols="3">
|
|
<colspec align="left" />
|
|
<colspec colnum="1" colname="col1" colwidth="1*"/>
|
|
<colspec colnum="2" colname="col4" colwidth="1*"/>
|
|
<colspec colnum="3" colname="col5" colwidth="2*"/>
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Attribute Name</entry>
|
|
<entry align="center">Allowed Values</entry>
|
|
<entry align="center">Attribute Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>port</entry>
|
|
<entry></entry>
|
|
<entry>The port on which the adapter listens.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>multicast</entry>
|
|
<entry>true, false</entry>
|
|
<entry>Whether or not the udp adapter uses multicast.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>multicast-address</entry>
|
|
<entry></entry>
|
|
<entry>When multicast is true, the multicast address to which the adapter
|
|
joins.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>pool-size</entry>
|
|
<entry></entry>
|
|
<entry>Specifies the concurrency. Specifies how many packets can
|
|
be handled concurrently.
|
|
It only applies if task-executor is not configured.
|
|
Defaults to 5.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>task-executor</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.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>receive-buffer-size</entry>
|
|
<entry></entry>
|
|
<entry>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..</entry>
|
|
</row>
|
|
<row>
|
|
<entry>check-length</entry>
|
|
<entry>true, false</entry>
|
|
<entry>Whether or not a udp adapter expects a data length field in the
|
|
packet received. Used to detect packet truncation.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>so-timeout</entry>
|
|
<entry></entry>
|
|
<entry>See <classname>java.net.DatagramSocket</classname>
|
|
setSoTimeout() methods for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>so-send-buffer-size</entry>
|
|
<entry></entry>
|
|
<entry>Used for udp acknowledgment packets. See <classname>java.net.DatagramSocket</classname>
|
|
setSendBufferSize() methods for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>so-receive-buffer- size</entry>
|
|
<entry></entry>
|
|
<entry>See <classname>java.net.DatagramSocket</classname>
|
|
setReceiveBufferSize() for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>local-address</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>error-channel</entry>
|
|
<entry></entry>
|
|
<entry>If an Exception is thrown by a downstream
|
|
component, the MessagingException message containing the exception
|
|
and failed message is sent to this channel.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table id="ip-ob-adapter-attributes">
|
|
<title>UDP Outbound Channel Adapter Attributes</title>
|
|
<tgroup cols="3">
|
|
<colspec align="left" />
|
|
<colspec colnum="1" colname="col1" colwidth="1*"/>
|
|
<colspec colnum="2" colname="col4" colwidth="1*"/>
|
|
<colspec colnum="3" colname="col5" colwidth="2*"/>
|
|
<thead>
|
|
<row>
|
|
<entry align="center">Attribute Name</entry>
|
|
<entry align="center">Allowed Values</entry>
|
|
<entry align="center">Attribute Description</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>host</entry>
|
|
<entry></entry>
|
|
<entry>The host name or ip address of the destination. For multicast udp
|
|
adapters, the multicast address.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>port</entry>
|
|
<entry></entry>
|
|
<entry>The port on the destination.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>multicast</entry>
|
|
<entry>true, false</entry>
|
|
<entry>Whether or not the udp adapter uses multicast.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>acknowledge</entry>
|
|
<entry>true, false</entry>
|
|
<entry>Whether or not a udp adapter requires an acknowledgment from the destination.
|
|
when enabled, requires setting the following 4 attributes.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ack-host</entry>
|
|
<entry></entry>
|
|
<entry>When acknowledge is true, indicates the host or ip address to which the
|
|
acknowledgment should be sent. Usually the current host, but may be
|
|
different, for example when Network Address Transaction (NAT) is
|
|
being used.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ack-port</entry>
|
|
<entry></entry>
|
|
<entry>When acknowledge is true, indicates the port to which the
|
|
acknowledgment should be sent. The adapter listens on this port for
|
|
acknowledgments.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>ack-timeout</entry>
|
|
<entry></entry>
|
|
<entry>When acknowledge is true, indicates the time in milliseconds that the
|
|
adapter will wait for an acknowledgment. If an acknowledgment is not
|
|
received in time, the adapter will throw an exception.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>min-acks-for- success</entry>
|
|
<entry></entry>
|
|
<entry>Defaults to 1. For multicast adapters, you can set this to a larger
|
|
value, requiring acknowledgments from multiple destinations.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>check-length</entry>
|
|
<entry>true, false</entry>
|
|
<entry>Whether or not a udp adapter includes a data length field in the
|
|
packet sent to the destination.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>time-to-live</entry>
|
|
<entry></entry>
|
|
<entry>For multicast adapters, specifies the time to live attribute for
|
|
the <classname>MulticastSocket</classname>; controls the scope
|
|
of the multicasts. Refer to the Java API
|
|
documentation for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>so-timeout</entry>
|
|
<entry></entry>
|
|
<entry>See <classname>java.net.DatagramSocket</classname>
|
|
setSoTimeout() methods for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>so-send-buffer-size</entry>
|
|
<entry></entry>
|
|
<entry>See <classname>java.net.DatagramSocket</classname>
|
|
setSendBufferSize() methods for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>so-receive-buffer- size</entry>
|
|
<entry></entry>
|
|
<entry>Used for udp acknowledgment packets. See <classname>java.net.DatagramSocket</classname>
|
|
setReceiveBufferSize() methods for more information.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>local-address</entry>
|
|
<entry></entry>
|
|
<entry>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.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>task-executor</entry>
|
|
<entry></entry>
|
|
<entry>
|
|
Specifies a specific Executor to be used for acknowledgment handling. If not supplied, an internal
|
|
single threaded executor will be used. Needed on some platforms that require the use of specific
|
|
task executors such as a WorkManagerTaskExecutor. One thread will be dedicated to handling
|
|
acknowledgments (if the acknowledge option is true).</entry>
|
|
</row>
|
|
</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>
|
|
<row>
|
|
<entry>error-channel</entry>
|
|
<entry></entry>
|
|
<entry>If an Exception is thrown by a downstream
|
|
component, the MessagingException message containing the exception
|
|
and failed message is sent to this channel.</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">
|
|
<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>connection-factory</entry>
|
|
<entry></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>
|
|
<row>
|
|
<entry>error-channel</entry>
|
|
<entry></entry>
|
|
<entry>If an Exception is thrown by a downstream
|
|
component, the MessagingException message containing the exception
|
|
and failed message is sent to this channel;
|
|
any reply from that flow will then be returned as a response by
|
|
the gateway.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
<table id="tcp-ob-gateway-attributes">
|
|
<title>TCP Outbound Gateway 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>connection-factory</entry>
|
|
<entry></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>
|
|
</table>
|
|
</para>
|
|
</section>
|
|
</chapter>
|