JBI Support deprecated in Apache ServiceMix 4
JBI 1.0 support is available in Apache ServiceMix 4 to allow existing users to migrate more easily to this latest version - if you're a new user, you should consider JBI deprecated and not use it for your project. Take a look at our technology selection guidelines for more information.
servicemix-ftp
Overview
The ServiceMix FTP component provides JBI integration to the FTP servers. It can be used to read & write files over FTPor to periodically poll directories for new files.
Namespace and xbean.xml
The namespace URI for the servicemix-bean JBI component is http://servicemix.apache.org/ftp/1.0. This is an example of an xbean.xml file with a namespace definition with prefix bean.
<beans xmlns:ftp="http://servicemix.apache.org/ftp/1.0">
<!-- add ftp:poller and ftp:sender definitions here -->
</beans>
Endpoint types
The servicemix-ftp component defines two endpoint type:
ftp:poller :: Periodically polls a directory on an FTP server for files and sends an exchange for every file
ftp:sender :: Writes the contents of an exchange to a file on an FTP server
ftp:poller
Endpoint properties
| Property Name | Type | Description |
|---|---|---|
| archive | java.net.URI | Specifies a directory relative to the polling directory to which processed files are archived. |
| autoCreateDirectory | boolean | Specifies if the endpoint should create the target directory, if it does not already exist. If you set this to <code>false</code> and the directory does not exist, the endpoint will not do anything. Default value is <code>true</code>. |
| changeWorkingDirectory | boolean | When set to <code>true</code>, the poller will do an explicit <code>cwd</code> into the directory to be polled. Default to <code>false</code>. Recursive polling will not be possible if this feature is enabled. |
| clientPool | org.apache.servicemix.ftp.FTPClientPool | Set a custom FTPClientPool. If this property has not been set, the FTP client pool will be created based on the information provided in the URI. |
| component | org.apache.servicemix.common.DefaultComponent | the <code>component</code> implementation to use |
| concurrentPolling | boolean | Sets whether more than one poll can be active at a time (true means yes). Default value is <code>false</code>. |
| delay | long | Sets the amount of time in milliseconds that the endpoint should wait before making the first poll. |
| deleteFile | boolean | Delete the file after it has been succesfully processed? Defaults to <code>true</code> |
| endpoint | java.lang.String | The name of the endpoint. |
| filter | java.io.FileFilter | Sets the filter to select which files have to be processed. When not set, all files will be picked up by the poller. |
| firstTime | java.util.Date | Sets the date on which the first poll will be executed. If a delay is also set using <code>setDelay</code>, the delay interval will be added after the date specified. |
| interfaceName | javax.xml.namespace.QName | The qualified name of the interface exposed by the endpoint. |
| lockManager | org.apache.servicemix.common.locks.LockManager | Set a custom LockManager implementation for keeping track of which files are already being processed. The default implementation is a simple, in-memory lock management system. |
| marshaler | org.apache.servicemix.components.util.FileMarshaler | Set a custom FileMarshaler implementation to control how the file contents is being translated into a JBI message. The default implementation reads XML contents from the file. |
| period | long | Sets the number of milliseconds between polling attempts. |
| recursive | boolean | Specifies whether subdirectories should be polled. Defaults to <code>true</code> |
| scheduler | org.apache.servicemix.common.scheduler.Scheduler | Set a custom Scheduler implementation if you need more fine-grained control over the polling schedule. |
| service | javax.xml.namespace.QName | The qualified name of the service the endpoint exposes. |
| serviceUnit | org.apache.servicemix.common.ServiceUnit | |
| stateless | boolean | When set to <code>false</code> |
| targetEndpoint | java.lang.String | the name of the endpoint to which requests are sent |
| targetInterface | javax.xml.namespace.QName | the QName of the interface to which requests are sent |
| targetOperation | javax.xml.namespace.QName | Set the operation to be invoked on the target service. |
| targetService | javax.xml.namespace.QName | the QName of the service to which requests are sent |
| targetUri | java.lang.String | Set the target service/endpoint/interface using a URI. |
| uri | java.net.URI | Configures the endpoint from a URI. |
ftp:sender
Endpoint properties
| Property Name | Type | Description |
|---|---|---|
| autoCreateDirectory | boolean | Specifies if the endpoint should create the target directory, if it does not already exist. If you set this to <code>false</code> and the directory does not exist, the endpoint will not do anything. Default value is <code>true</code>. |
| checkDuplicates | boolean | Specifies whether duplicates should be checked. Defaults to <code>true</code>. |
| clientPool | org.apache.servicemix.ftp.FTPClientPool | Set a custom FTPClientPool. If this property has not been set, the FTP client pool will be created based on the information provided in the URI. |
| component | org.apache.servicemix.ftp.FtpComponent | |
| endpoint | java.lang.String | The name of the endpoint. |
| interfaceName | javax.xml.namespace.QName | The qualified name of the interface exposed by the endpoint. |
| marshaler | org.apache.servicemix.components.util.FileMarshaler | Set a custom FileMarshaler implementation to control how the file contents is being translated into a JBI message. The default implementation reads XML contents from the file. |
| overwrite | boolean | Specifies if a file with the same name already exists on the FTP server, the file should be overwritten. Defaults to <code>false</code>. |
| service | javax.xml.namespace.QName | The qualified name of the service the endpoint exposes. |
| uniqueFileName | java.lang.String | Sets the name used to make a unique name if no file name is available on the message. |
| uploadPrefix | java.lang.String | Set the file name prefix used during upload. The prefix will be automatically removed as soon as the upload has completed. This allows other processes to discern completed files from files that are being uploaded. |
| uploadSuffix | java.lang.String | Set the file name suffix used during upload. The suffix will be automatically removed as soon as the upload has completed. This allows other processes to discern completed files from files that are being uploaded. |
| uri | java.net.URI | Configures the endpoint from a URI |
Examples
Using ftp:pool to configure the FTP connections
In order to gain more control over the FTP connection parameters (active/passive, timeout, ...) that are being used, you can define your own FTP connection pool. Afterward, you can refer to the pool object from both a sender and poller endpoint.
<?xml version="1.0"?>
<beans xmlns:ftp="http://servicemix.apache.org/ftp/1.0"
xmlns:sample="urn:servicemix:example">
<ftp:sender service="sample:sender" endpoint="endpoint"
uri="ftp://localhost/myfolder"
clientPool="#clientPool"/>
<ftp:pool id="clientPool" username="myname" password="$ecret"
dataTimeout="90000" />
</beans>
The table below shows the full list of options offered by ftp:pool:
| Property Name | Type | Description |
|---|---|---|
| address | java.net.InetAddress | Set the remote internet address to connect to. |
| binaryMode | boolean | Use binary mode transfers. Defaults to <code>true</code>. |
| config | org.apache.commons.net.ftp.FTPClientConfig | Configure a custom FTPClientConfig instance to allow more fine-grained control over the FTP connections in the pool. |
| controlEncoding | java.lang.String | Configure the encoding used in the FTP control connections. Defaults to <code>ISO-8859-1</code> |
| dataTimeout | int | Specifies a timeout used on the FTP data connection. Defaults to <code>120000</code> |
| host | java.lang.String | Set the remote host name to connect to. |
| localAddress | java.net.InetAddress | Set the local IP address to be used when establishing the connection. |
| localPort | int | Set the local TCP/IP port to be used when establishing the connection. |
| passiveMode | boolean | Use passive mode FTP transfers. Defaults to <code>false</code> |
| password | java.lang.String | Set the password for logging into the FTP server. |
| pool | org.apache.commons.pool.ObjectPool | Set a custom ObjectPool instance to use for the connection pooling. |
| port | int | Set the remote port number to connect to. |
| username | java.lang.String | Set the login to use to access the FTP server. |
If you need even more fine-grained control over the FTP connections or the way the payloads are being handled, have a look at the Camel FTP component, which offers a lot of options out of the box, but also allows setting any property on its underlying Commons NET FTPClient and FTPClientConfig instances.