diff --git a/docs/src/reference/docbook/ftp.xml b/docs/src/reference/docbook/ftp.xml index 9a8262020a..27a0d85e93 100644 --- a/docs/src/reference/docbook/ftp.xml +++ b/docs/src/reference/docbook/ftp.xml @@ -3,27 +3,27 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> FTP/FTPS Adapters - Spring Integration provides support for file transfer operations via FTP and FTPS + Spring Integration provides support for file transfer operations via FTP and FTPS.
Introduction - File Transfer Protocol (FTP) is a simple network protocol which allows you to transfer files between two computers on the Internet. + 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 client which initiates a connection to a remote computer - running an FTP server software. After the connection is established, the client can choose + 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 clients - - Inbound Channel Adapters and Outbound Channel Adapters as well as convenient - namespace configuration to define these clients. + 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. - FTP + To use the FTP namespace, add the following to the header of your XML file: FTP Session Factory - Before configuring FTP adapters you must configure Ftp Session Factory. You configure - Ftp Session Factory via regular bean configuration by configuring org.springframework.integration.ftp.session.DefaultFtpSessionFactory: + 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: @@ -49,7 +49,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp ]]> - For FTPS connections all you need to do is use org.springframework.integration.ftp.session.DefaultFtpsSessionFactory. + For FTPS connections all you need to do is use org.springframework.integration.ftp.session.DefaultFtpsSessionFactory instead. Below is the complete configuration sample: @@ -74,13 +74,13 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp - Now all you need to do is inject these session factories into your adapters. Obviously the protocol (FTP or FTPS) adapter will - use depends on the type of session factory that's been injected into the adapter. + 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. - A more practical way to provide values for Ftp/Ftps Session Factory 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) + 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).
@@ -88,7 +88,7 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp
FTP Inbound Channel Adapter - FTP Inbound Channel Adapter is a special listener that will connect to the FTP server and will listen + 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. + remote-directory="some/remote/path" + local-directory="."> ]]> - As you can see form the configuration above you can configure FTP Inbound Channel Adapter via inbound-channel-adapter - element while also providing values for various attributes such as local-working-directory, filename-pattern - (based on simple pattern matching - not regex) and of course the reference to a session-factory. + 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 enough. If this is the case, you can use filename-regex attribute to specify Regular expression + 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 reference to a custom implementation of the - org.springframework.integration.file.filters.FileListFilter - a strategy interface for filtering a - group of files. + 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 FTP Inbound Channel Adapter is a polling consumer and - therefore you must configure a poller (global or local). - Once the file has been transferred a Message with java.io.File being a payload will be generated and sent to the channel - identified with channel attribute. + 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 file - will be written with some temporary extension (e.g., foo.txt.writing) and then renamed after the writing process finished. + 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 use filtering support provided via filename-pattern, filename-regex - and filter attributes. We also provide a convenient Regex-based implementation - org.springframework.integration.ftp.filters.FtpPatternMatchingFileListFilter. + 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. + filter="customFilter" + local-directory="file:/my_transfers"> + remote-directory="some/remote/path" - - -]]> + +]]>
@@ -153,28 +152,29 @@ xsi:schemaLocation="http://www.springframework.org/schema/integration/ftp FTP Outbound Channel Adapter - FTP Outbound Channel Adapter is a special MessageHandler 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 File so you are not limited only to the File object. 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[] - byte array that represents the file contents; 3) java.lang.String - - represents the file contents. + 2) byte[] - a byte array that represents the file contents; and 3) java.lang.String - + text that represents the file contents. ]]> - - - As you can see form the configuration above you can configure FTP Outbound Channel Adapter via + + 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 - (implementation of org.springframework.integration.file.FileNameGenerator), reference to a client-factory - as well as other attributes. Please refer to the schema for more details on these attributes. + (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. - By default Spring Integration will use org.springframework.integration.file.DefaultFileNameGenerator (if non specified). - DefaultFileNameGenerator will determine the file name based on the value of the file_name header (if exists) in your - MessageHeaders or if the payload of the Message is java.io.File, then it will use the original name of the file. + 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.