INT-1546 Tcp Interceptors - polish and doc

spring-integration-ip/src/main/java/org/springframework/integration/ip/tcp/connection/TcpConnectionInterceptorFactory.java

@@ -17,15 +17,20 @@ package org.springframework.integration.ip.tcp.connection;
 
 
 /**
- * Base class for TcpConnectionInterceptorFactories. Subclasses create prototype beans by
- * default.
+ * Interface for TCP connection interceptor factories. 
  * 
  * @author Gary Russell
  * @since 2.0
  *
  */
-public abstract class TcpConnectionInterceptorFactory {
+public interface TcpConnectionInterceptorFactory {
 
+	/**
+	 * Called for each new connection - if an interceptor is
+	 * stateful, a new interceptor must be returned on each call.
+	 *  
+	 * @return the TcpInterceptor 
+	 */
 	public abstract TcpConnectionInterceptor getInterceptor();
 }
 

spring-integration-ip/src/test/java/org/springframework/integration/ip/tcp/connection/HelloWorldInterceptorFactory.java

@@ -21,7 +21,7 @@ package org.springframework.integration.ip.tcp.connection;
  * @since 2.0
  *
  */
-public class HelloWorldInterceptorFactory extends
+public class HelloWorldInterceptorFactory implements
 		TcpConnectionInterceptorFactory {
 
 	private String hello = "Hello";
@@ -41,7 +41,6 @@ public class HelloWorldInterceptorFactory extends
 	}
 
 
-	@Override
 	public TcpConnectionInterceptor getInterceptor() {
 		return new HelloWorldInterceptor(hello, world);
 	}

src/docbkx/ip.xml

@@ -250,15 +250,78 @@
       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.
-        Further documentation to follow.
+        No interceptors are currently provided by the framework but, for an example, 
+        see the <classname>InterceptedSharedConnectionTests</classname> in the source
+        repository.
     </para>
     <para>
-      For full details of the attributes available on connection factories, see the 
-      reference at the end of this section.
+        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">