159 lines
8.5 KiB
XML
159 lines
8.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="Sftp"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<title>SFTP Adapters</title>
|
|
<para>
|
|
Spring Integration provides support for file transfer operations via SFTP
|
|
</para>
|
|
<section id="sftp-intro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
Secure File Transfer Protocol (SFTP) is a network protocol which allows you to transfer
|
|
files between two computers on the Internet over any reliable stream.
|
|
</para>
|
|
|
|
<para>
|
|
SFTP protocol requires secure channel, such as SSH, as well as visibility to client's identity throughout SFTP session.
|
|
</para>
|
|
|
|
<para>
|
|
Spring Integration supports sending and receiving files over SFTP by providing two types of <emphasis>client</emphasis>s -
|
|
<emphasis>Inbound Channel Adapters</emphasis> and <emphasis>Outbound Channel Adapters</emphasis> as well as convenient
|
|
namespace configuration to define these <emphasis>client</emphasis>s.
|
|
|
|
<programlisting language="xml"><![CDATA[xmlns:sftp="http://www.springframework.org/schema/integration/sftp"
|
|
xsi:schemaLocation="http://www.springframework.org/schema/integration/sftp
|
|
http://www.springframework.org/schema/integration/sftp/spring-integration-sftp-2.0.xsd"
|
|
]]></programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="sftp-session-factory">
|
|
<title>SFTP Session Factory</title>
|
|
<para>
|
|
Before configuring SFTP adapters you must configure <emphasis>Sftp Session Factory</emphasis>. You configure
|
|
<emphasis>Sftp Session Factory</emphasis> via regular bean configuration:
|
|
Below is a basic configuration:
|
|
|
|
<programlisting language="xml"><![CDATA[<beans:bean id="sftpSessionFactory" class="org.springframework.integration.sftp.session.SftpSessionFactory">
|
|
<beans:property name="host" value="loclahost"/>
|
|
<beans:property name="privateKey" value="classpath:META-INF/keys/sftpTest"/>
|
|
<beans:property name="privateKeyPassphrase" value="springIntegration"/>
|
|
<beans:property name="port" value="22"/>
|
|
<beans:property name="user" value="kermit"/>
|
|
</beans:bean>]]></programlisting>
|
|
|
|
|
|
Now all you need to do is inject this <emphasis>Sftp Session Factory</emphasis> into your adapters.
|
|
</para>
|
|
<para>
|
|
<note>
|
|
A more practical way to provide values for <emphasis>Sftp Session Factory</emphasis> 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>
|
|
</section>
|
|
|
|
<section id="sftp-inbound">
|
|
<title>SFTP Inbound Channel Adapter</title>
|
|
<para>
|
|
<emphasis>SFTP 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[<sftp:inbound-channel-adapter id="sftpAdapterAutoCreate"
|
|
session-factory="sftpSessionFactory"
|
|
channel="requestChannel"
|
|
filename-pattern="*.txt"
|
|
remote-directory="/foo/bar"
|
|
local-directory="file:target/foo"
|
|
auto-create-local-directory="true"
|
|
delete-remote-files="false">
|
|
<poller fixed-rate="1000"/>
|
|
</sftp:inbound-channel-adapter>]]></programlisting>
|
|
|
|
As you can see form the configuration above you can configure <emphasis>SFTP Inbound Channel Adapter</emphasis> via
|
|
<code>inbound-channel-adapter</code> element while also providing values for various attributes such as <code>local-directory</code>
|
|
- where files are going to be transfered TO and <code>remote-directory</code> - the remote source directory
|
|
as well as other attributes including <code>session-factory</code> which we configured earlier.
|
|
</para>
|
|
<para>
|
|
Some times file filtering based on the simple pattern specified via <code>filename-pattern</code> attribute might not be
|
|
sufficient enough. If this is the case, you can use <code>filename-regex</code> attribute to specify Regular expression
|
|
(e.g. <code>filename-regex=".*\.test$"</code>). And of course if you need complete control you can use <code>filter</code>
|
|
attribute and provide reference to a custom implementation of the
|
|
<classname>org.springframework.integration.file.filters.FileListFilter</classname> - a strategy interface for filtering a
|
|
group of files.
|
|
</para>
|
|
<para>
|
|
Please refer to the schema for more details on these attributes.
|
|
</para>
|
|
|
|
<para>
|
|
It is also important to understand that <emphasis>SFTP Inbound Channel Adapter</emphasis> is a polling consumer and therefore
|
|
you must configure a poller (global or local)
|
|
Once the file has been transferred to a local directory 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>
|
|
<para>
|
|
<emphasis>More on File Filtering and Large Files</emphasis>
|
|
</para>
|
|
<para>
|
|
Some times the file that just appeared in the monitored (remote) directory is not complete. Typically such 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 use filtering support provided via <code>filename-pattern</code>, <code>filename-regex</code>
|
|
and <code>filter</code> attributes. We also provide a convenient Regex-based implementation
|
|
<classname>org.springframework.integration.sftp.filters.SftpPatternMatchingFileListFilter</classname>.
|
|
Once configured all you need is include such filter in your adapter via <code>filter</code> attribute.
|
|
|
|
<programlisting language="xml"><![CDATA[<int-sftp:inbound-channel-adapter id="sftpInbondAdapter"
|
|
channel="receiveChannel"
|
|
session-factory="sftpSessionFactory"
|
|
local-directory="file:/local-test-dir"
|
|
remote-directory="/remote-test-dir">
|
|
<int:poller fixed-rate="1000" max-messages-per-poll="10" task-executor="executor"/>
|
|
</int-sftp:inbound-channel-adapter>
|
|
|
|
<bean id="fileNameFilter"
|
|
class="org.springframework.integration.ftp.filters.FtpPatternMatchingFileListFilt"">
|
|
<constructor-arg value=".*\.txt$"/>
|
|
</bean>]]></programlisting>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="sftp-outbound">
|
|
<title>SFTP Outbound Channel Adapter</title>
|
|
|
|
<para>
|
|
<emphasis>SFTP Outbound Channel Adapter </emphasis>is a special <classname>MessageHandler</classname> that will connect to the
|
|
remote directory and will initiate a file transfer for every file it will receive as a payload of the <classname>Message</classname>.
|
|
It also supports several representation of the File so you are not limited to the File object.
|
|
Similar to FTP outbound adapter <emphasis>SFTP 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 contents.
|
|
|
|
<programlisting language="xml"><![CDATA[<int-sftp:outbound-channel-adapter id="sftpOutboundAdapter"
|
|
session-factory="sftpSessionFactory"
|
|
channel="inputChannel"
|
|
charset="UTF-8"
|
|
remote-directory="foo/bar"
|
|
remote-filename-generator-expression="payload.getName() + '-foo'"/>]]></programlisting>
|
|
|
|
As you can see form the configuration above you can configure <emphasis>SFTP Outbound Channel Adapter</emphasis> via
|
|
<code>outbound-channel-adapter</code>.
|
|
Please refer to the schema for more details on these attributes.
|
|
</para>
|
|
<para>
|
|
<emphasis>SpEL and SFTP Outbound Adapter</emphasis>
|
|
</para>
|
|
<para>
|
|
As with many other components in Spring Integration, you can benefit from Spring Expression Language (SpEL) when configuring
|
|
<emphasis>SFTP Outbound Channel Adapter</emphasis>, by specifying two attributes <code>remote-directory-expression</code> and
|
|
<code>remote-filename-generator-expression</code> (see above). Expression evaluation context will have Message as its root object, thus allowing
|
|
you to provide expressions which can dynamically compute the <emphasis>file name</emphasis> or the existing <emphasis>directory path</emphasis>
|
|
based on the data in the Message. In the example above we are defining <code>remote-filename-generator-expression</code> attribute with expression
|
|
value which computes the <emphasis>file name</emphasis> based on its original name while also appending suffix '-foo'.
|
|
</para>
|
|
</section>
|
|
</chapter>
|