12. FTP/FTPS Adapters

Spring Integration provides support for file transfer operations via FTP and FTPS.

12.1 Introduction

The File Transfer Protocol (FTP) is a simple network protocol which allows you to transfer files between two computers on the Internet.

There are two actors when it comes to FTP communication: client and server. To transfer files with FTP/FTPS, you use a client which initiates a connection to a remote computer that is running an FTP server. After the connection is established, the client can choose to send and/or receive copies of files.

Spring Integration supports sending and receiving files over FTP/FTPS by providing two types of client side adapters: Inbound Channel Adapter and Outbound Channel Adapter. It also provides convenient namespace-based configuration options for defining these client components.

To use the FTP namespace, add the following to the header of your XML file:

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" 

12.2 FTP Session Factory

Before configuring FTP adapters you must configure an FTP Session Factory. You can configure the FTP Session Factory with a regular bean definition where the implementation class is org.springframework.integration.ftp.session.DefaultFtpSessionFactory: Below is a basic configuration:

<bean id="ftpClientFactory" 
	class="org.springframework.integration.ftp.session.DefaultFtpSessionFactory">
		<property name="host" value="localhost"/>
		<property name="port" value="22"/>
		<property name="username" value="kermit"/>
		<property name="password" value="frog"/>
		<property name="clientMode" value="0"/>
		<property name="fileType" value="2"/>
</bean>

For FTPS connections all you need to do is use org.springframework.integration.ftp.session.DefaultFtpsSessionFactory instead. Below is the complete configuration sample:

<bean id="ftpClientFactory" 
	class="org.springframework.integration.ftp.client.DefaultFtpsClientFactory">
		<property name="host" value="localhost"/>
		<property name="port" value="22"/>
		<property name="username" value="oleg"/>
		<property name="password" value="password"/>
		<property name="clientMode" value="1"/>
		<property name="fileType" value="2"/>
		<property name="useClientMode" value="true"/>
		<property name="cipherSuites" value="a,b.c"/>
		<property name="keyManager" ref="keyManager"/>
		<property name="protocol" value="SSL"/>
		<property name="trustManager" ref="trustManager"/>
		<property name="prot" value="P"/>
		<property name="needClientAuth" value="true"/>
		<property name="authValue" value="oleg"/>
		<property name="sessionCreation" value="true"/>
		<property name="protocols" value="SSL, TLS"/>
		<property name="implicit" value="true"/>
</bean>

Now all you need to do is inject these session factories into your adapters. Obviously the protocol (FTP or FTPS) that an adapter will use depends on the type of session factory that has been injected into the adapter.

[Note]Note
A more practical way to provide values for FTP/FTPS Session Factories is by using Spring's property placeholder support (See: http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-factory-placeholderconfigurer).

12.3 FTP Inbound Channel Adapter

The FTP Inbound Channel Adapter 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.

<int-ftp:inbound-channel-adapter id="ftpInbound"
				channel="ftpChannel" 
				session-factory="ftpSessionFactory"
				charset="UTF-8"
				auto-create-local-directory="true"
				delete-remote-files="true"
				filename-pattern="*.txt"
				remote-directory="some/remote/path"
				local-directory=".">
			<int:poller fixed-rate="1000"/>
</int-ftp:inbound-channel-adapter>

As you can see from the configuration above you can configure an FTP Inbound Channel Adapter via the inbound-channel-adapter element while also providing values for various attributes such as local-directory, filename-pattern (which is based on simple pattern matching, not regular expressions), and of course the reference to a session-factory.

Some times file filtering based on the simple pattern specified via filename-pattern attribute might not be sufficient. If this is the case, you can use the filename-regex attribute to specify a Regular Expression (e.g. filename-regex=".*\.test$"). And of course if you need complete control you can use filter attribute and provide a reference to any custom implementation of the org.springframework.integration.file.filters.FileListFilter, a strategy interface for filtering a list of files.

Please refer to the schema for more details on these attributes.

It is also important to understand that the FTP Inbound Channel Adapter is a Polling Consumer and therefore you must configure a poller (either via a global default or a local sub-element). Once a file has been transferred, a Message with a java.io.File as its payload will be generated and sent to the channel identified by the channel attribute.

More on File Filtering and Large Files

Some times the file that just appeared in the monitored (remote) directory is not complete. Typically such a file will be written with some temporary extension (e.g., foo.txt.writing) and then renamed after the writing process finished. As a user in most cases you are only interested in files that are complete and would like to filter only files that are complete. To handle these scenarios you can use the filtering support provided by the filename-pattern, filename-regex and filter attributes. Here is an example that uses a custom Filter implementation.

<int-ftp:inbound-channel-adapter 
			channel="ftpChannel" 
			session-factory="ftpSessionFactory"
			filter="customFilter"
			local-directory="file:/my_transfers">
			remote-directory="some/remote/path"
	<int:poller fixed-rate="1000"/>
</int-ftp:inbound-channel-adapter>
	
<bean id="customFilter" class="org.example.CustomFilter"/>

12.4 FTP Outbound Channel Adapter

The FTP Outbound Channel Adapter relies upon a MessageHandler implementation that will connect to the FTP server and initiate an FTP transfer for every file it receives in the payload of incoming Messages. It also supports several representations of the File so you are not limited only to java.io.File typed payloads. The FTP Outbound Channel Adapter supports the following payloads: 1) java.io.File - the actual file object; 2) byte[] - a byte array that represents the file contents; and 3) java.lang.String - text that represents the file contents.

<int-ftp:outbound-channel-adapter id="ftpOutbound"
				channel="ftpChannel" 
				session-factory="ftpSessionFactory"
				charset="UTF-8"
				filename-generator="fileNameGenerator"/>

As you can see from the configuration above you can configure an FTP Outbound Channel Adapter via the outbound-channel-adapter element while also providing values for various attributes such as filename-generator (an implementation of the org.springframework.integration.file.FileNameGenerator strategy interface), a reference to a client-factory, as well as other attributes. Please refer to the schema for more details on the available attributes.

[Note]Note
By default Spring Integration will use org.springframework.integration.file.DefaultFileNameGenerator if none is specified. DefaultFileNameGenerator will determine the file name based on the value of the file_name header (if it exists) in the MessageHeaders, or if the payload of the Message is already a java.io.File, then it will use the original name of that file.