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

INT-1544 TCP Doc polishing

Browse Source
This commit is contained in:
Gary Russell
2010-10-23 10:43:54 -04:00
parent c98af91aa6
commit b8709b3316
1 changed files with 46 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
src/docbkx/ip.xml
View File

@@ -22,9 +22,6 @@
<para>
TCP inbound and outbound adapters are provided <classname>TcpSendingMessageHandler</classname>
sends messages over TCP. <classname>TcpReceivingChannelAdapter</classname> receives messages over TCP.
<tip>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.</tip>
</para>
<para>
An inbound TCP gateway is provided; this allows for simple request/response processing. While
@@ -36,7 +33,8 @@
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.
the calling thread blocks on the connection until either a response is received or a timeout
or I/O error occurs.
</para>
</section>
<section id="udp-adapters">
@@ -138,7 +136,7 @@
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
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.
@@ -216,32 +214,38 @@
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. For backwards compatibility, connections using any of these
three serializers will also accept a String which will be converted to a byte array first.
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.common.serializer.DefaultSerializer</classname> which can be used to convert any
Serializable objects using java serialization.
<classname>org.springframework.common.serializer.DefaultDeserializer</classname> is provided for
inbound deserialization.
We expect to provide other serialization technologies but you may also
supply your own by implementing the <classname>Deserializer</classname> and
<classname>Serializer</classname> interfaces. If you do not wish to use
the default (de)serializers, you must supply <classname>serializer</classname> and
<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="serializer"
class="org.springframework.commons.serializer.DefaultSerializer" />
<bean id="deserializer"
class="org.springframework.commons.serializer.DefaultDeserializer" />
<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="deserializer"
serializer="serializer"
deserializer="JavaDeserializer"
serializer="javaSerializer"
/>]]></programlisting>
A server connection factory that uses <classname>java.net.Socket</classname>
connections and uses Java serialization on the wire.
@@ -253,7 +257,7 @@
Further documentation to follow.
</para>
<para>
For a full reference of the attributes available on connection factories, see the
For full details of the attributes available on connection factories, see the
reference at the end of this section.
</para>
</section>
@@ -265,7 +269,7 @@
<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 indicates which connection factory is to be used to
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
@@ -274,14 +278,16 @@
</para>
<para>
<programlisting language="xml"><![CDATA[
<bean id="serializer" class="org.springframework.commons.serializer.DefaultSerializer" />
<bean id="deserializer" class="org.springframework.commons.serializer.DefaultDeserializer" />
<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="deserializer"
serializer="serializer"
deserializer="javaDeserializer"
serializer="javaSerializer"
using-nio="true"
single-use="true"
/>
@@ -292,8 +298,8 @@
port="#{server.port}"
single-use="true"
so-timeout="10000"
deserializer="deserializer"
serializer="serializer"
deserializer="javaDeserializer"
serializer="javaSerializer"
/>
<int:channel id="input" />
@@ -324,7 +330,8 @@
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'.
'inboundClient' and deposited in channel 'replies'. Java
serialization is used on the wire.
</para>
</section>
<section id="tcp-gateways">
@@ -336,15 +343,15 @@
can process a single request/response at a time.
</para>
<para>
After constructing a message with the incoming payload and sending
it to the requestChannel, it waits for a response and sends the payload
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>
<para>
After sending a message over the connection, the thread waits for a response and
constructs a response message
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
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
@@ -358,8 +365,8 @@
connection-factory="cfServer"
reply-timeout="10000"
/>]]></programlisting>
A simple inbound TCP gateway; if a default connection factory is used,
messages will be \r\n delimited data and the gateway can be
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>
@@ -556,7 +563,7 @@
</table>
<table id="ip-ob-adapter-attributes">
<title>UDP Outbound Channel Adapter Attributes</title>
<tgroup cols="5">
<tgroup cols="3">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col4" colwidth="1*"/>
@@ -673,7 +680,7 @@
</table>
<table id="ip-ib-adapter-attributes">
<title>UDP Inbound Channel Adapter Attributes</title>
<tgroup cols="5">
<tgroup cols="3">
<colspec align="left" />
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col4" colwidth="1*"/>