From f72cab116c333cee9d7a987fbcde44fd4789f3f4 Mon Sep 17 00:00:00 2001
From: Oleg Zhurakousky <ozhurakousky@vmware.com>
Date: Sat, 13 Nov 2010 08:44:38 -0500
Subject: [PATCH] INT-1559 added docs for FTP/FTPS

---
 docs/src/reference/docbook/ftp.xml | 129 ++++++++++++++++++++++++++++-
 1 file changed, 126 insertions(+), 3 deletions(-)

diff --git a/docs/src/reference/docbook/ftp.xml b/docs/src/reference/docbook/ftp.xml
index 9e9df9d580..1937d696a7 100644
--- a/docs/src/reference/docbook/ftp.xml
+++ b/docs/src/reference/docbook/ftp.xml
@@ -1,14 +1,137 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ftp"
     xmlns:xlink="http://www.w3.org/1999/xlink">
-  <title>FTP Adapter</title>
+  <title>FTP/FTPS Adapters</title>
   <para>
-    Spring Integration provides support for FTP 
+    Spring Integration provides support for FTP and FTPS 
   </para>
   <section id="ftp-intro">
     <title>Introduction</title>
     <para>
-      TODO
+      File Transfer Protocol (FTP) is a simple network protocol which allows you to transfer files between two computers on the Internet.
+    </para>
+    <para>
+    There are two actors when it comes to FTP communication - <emphasis>client</emphasis> and <emphasis>server</emphasis>. 
+    To transfer files with FTP/FTPS, you use <emphasis>client</emphasis> which initiates a connection to a remote computer 
+    running an FTP <emphasis>server</emphasis> software. After the connection is established, the <emphasis>client</emphasis> can choose 
+    to send and/or receive copies of files. 
+    </para>
+    
+    <para>
+    Spring Integration supports sending and receiving files over FTP/FTPS by providing two types of <emphasis>client</emphasis>s - 
+    Inbound Channel Adapters and Outbound Channel Adapters as well as convenient namespace configuration to define these 
+    <emphasis>client</emphasis>s.
+    </para>
+    <para>
+    	<emphasis>FTP</emphasis>
+    	<programlisting language="xml"><![CDATA[xmlns:ftp="http://www.springframework.org/schema/integration/ftp"
+xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp 
+	http://www.springframework.org/schema/integration/ftp/spring-integration-ftp-2.0.xsd" 
+]]></programlisting>
+    </para>
+    
+    <para>
+    	<emphasis>FTPS</emphasis>
+    	<programlisting language="xml"><![CDATA[xmlns:ftps="http://www.springframework.org/schema/integration/ftps"
+xsi:schemaLocation="http://www.springframework.org/schema/integration/ftps 
+	http://www.springframework.org/schema/integration/ftp/spring-integration-ftps-2.0.xsd" 
+]]></programlisting>
     </para>
   </section>
+  
+  <section id="ftp-inbound">
+  	<title>FTP Inbound Channel Adapter</title>
+  	<para>
+  	<emphasis>FTP Inbound Channel Adapter</emphasis> is a special listener that will connect to the FTP server and will listen 
+  	for the remote directory events (e.g., new file created) at which point it will initiate a file transfer.
+  	
+  	<programlisting language="xml"><![CDATA[<ftp:inbound-channel-adapter 
+		remote-directory="/foo/bar/ftp/files" 
+		channel="ftpIn" 
+		host="localhost" 
+		auto-delete-remote-files-on-sync="false"
+		username="user" 
+		password="password" 
+		port="21"	 
+		filename-pattern=".*?txt">
+	<int:poller fixed-rate="1000"/>
+</ftp:inbound-channel-adapter>]]></programlisting>
+
+	As you can see form the configuration above you can configure <emphasis>FTP Inbound Channel Adapter</emphasis> via <code>inbound-channel-adapter</code> 
+	element while also providing values for various attributes such as <code>user</code> and <code>password</code> to connect to an FTP server, 
+	as well as other attributes. Please refer to the schema for more details on these attributes. 
+  	</para>
+  	<para>
+  	It is also important to understand that <emphasis>FTP Inbound Channel Adapter</emphasis> is a <emphasis>polling consumer</emphasis> and 
+  	therefore you must configure a poller (global or local).
+    Once the file has been transferred a Message with <classname>java.io.File</classname> being a payload will be generated and sent to the channel 
+    identified with <code>channel</code> attribute.
+  	</para>
+  </section>
+  
+  <section id="ftps-inbound">
+  	<title>FTPS Inbound Channel Adapter</title>
+  	<para>
+  	<emphasis>FTPS Inbound Channel Adapter</emphasis> adds support for secured file <emphasis>receive operations</emphasis> with 
+  	FTP servers that support Transport Layer Security (TLS). Configuration of the adapter itself is very similar to the 
+  	FTP Inbound Channel Adapter and is use the same <code>inbound-channel-adapter</code> element but from the FTPS namespace.
+  	
+  	  	<programlisting language="xml"><![CDATA[<ftps:inbound-channel-adapter 
+		remote-directory="/foo/bar/ftp/files" 
+		channel="ftpIn" 
+		host="localhost" 
+		auto-delete-remote-files-on-sync="false"
+		username="user" 
+		password="password" 
+		port="2222"	 
+		filename-pattern=".*?txt">
+	<int:poller fixed-rate="1000"/>
+</ftps:inbound-channel-adapter>]]></programlisting>	
+  	</para>
+  </section>
+  
+  <section id="ftp-outbound">
+  	<title>FTP Outbound Channel Adapter</title>
+  	
+  	<para>
+  	<emphasis>FTP Outbound Channel Adapter</emphasis> is a special <classname>MessageHandler</classname> that will connect to the 
+  	FTP server and will initiate an FTP transfer for every file it will receive in the payload of the Message. It also supports several 
+  	representation of the <emphasis>File</emphasis> so you are not limited only to the File object. <emphasis>FTP Outbound Channel Adapter</emphasis> 
+  	supports the following payloads: 1) <classname>java.io.File</classname> - the actual file object; 
+  	2) <classname>byte[]</classname> - byte array that represents the file contents; 3) <classname>java.lang.String</classname> - 
+  	represents the file path.
+  	
+  	<programlisting language="xml"><![CDATA[<ftp:outbound-channel-adapter
+			remote-directory="${ftp.remotedir}"
+			channel="ftpOutbound"
+			host="${ftp.host}"
+			file-type="binary-file-type"
+			username="${ftp.username}"
+			password="${ftp.password}" 
+			port="2222"
+			client-mode="passive-local-data-connection-mode"/>]]></programlisting>	
+			
+	As you can see form the configuration above you can configure <emphasis>FTP Outbound Channel Adapter</emphasis> via 
+	<code>outbound-channel-adapter</code> element while also providing values for various attributes such as <code>user</code> 
+	and <code>password</code> to connect to an FTP server, as well as other attributes. Please refer to the schema for
+	 more details on these attributes. 
+  	</para>
+  </section>
+  
+  <section id="ftps-outbound">
+  	<title>FTPS Outbound Channel Adapter</title>
+  	<para>
+  	<emphasis>FTPS Outbound Channel Adapter</emphasis> adds support for secured file send operations with FTP servers that support 
+  	Transport Layer Security (TLS). Configuration of the adapter itself is very similar to the
+  	 <emphasis>FTP Outbound Channel Adapter</emphasis> and is use the same <code>outbound-channel-adapter</code> element but 
+  	 from the FTPS namespace:
+  	</para>
+  </section>
+  
+  <para>
+  	<note>
+  	A more practical way to configure these types of adapters would be via Spring's property 
+  	placeholder (http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer)	
+  	</note>
+  </para>
 </chapter>