The SFTP Transport allows files to be read and written to and from directories over SFTP.
Unlike the VFS Transport, it can handle large files because it streams message payloads.
The SFTP connector is based on the JSCH library, version 0.1.42.
An Installation Guide is available. Examples can be found in the Functional Tests section below.
Versions of the SFTP Transport are available for each major version of Mule:
SFTP Endpoints
SFTP endpoints are expressed using the standard URI of:
sftp://<username>:<password>@<host>:<port>/path/to/dir
For example, the SFTP endpoint could be configured as follows:
sftp://mule:test123@myhost.com/tmp/sftp
This endpoint would connect over SFTP to myhost.com as mule/test123, then read or write to /tmp/sftp.
An alternate format for addressing folders relative the home-folder is:
sftp://mule:test123@myhost.com/~/tmp/sftp
SFTP Connector
The SFTP connector configures the default behavior for SFTP endpoints that reference the connector. If there is only one SFTP connector configured, all SFTP endpoints will use that connector.
The SFTP connector takes the same attributes as the SFTP Inbound Endpoint and the SFTP Outbound Endpoint.
The connector also takes the following attributes:
| Name |
Type |
Req. |
Default |
Description |
maxConnectionPoolSize
|
int
|
no
|
disabled
|
If the number of active connections is specified, then a connection pool will be used with active connections up to this number. Use a negative value for no limit. If the value is zero no connection pool will be used.
|
| tempDirInbound |
string |
no |
disabled |
See tempDir on inbound endpoint for more information |
| tempDirOutbound |
string |
no |
disabled |
See tempDir on outbound endpoint for more information |
SFTP Endpiont
A global SFTP endpoint takes the same attributes as the SFTP Inbound Endpoint and the SFTP Outbound Endpoint.
SFTP Inbound Endpoint
SFTP specific attributes of <sftp:inbound-endpoint> elements
| Name |
Type |
Req. |
Default |
Description |
identityFile
|
string
|
no
|
disabled
|
An identityFile location for a PKI private key.
|
passphrase
|
string
|
no
|
disabled
|
The passphrase (password) for the identityFile if required.
|
| pollingFrequency |
long |
no |
1000 |
The frequency in milliseconds that the read directory should be checked. Note that the read directory is specified by the endpoint of the listening component. |
autoDelete
|
boolean
|
no
|
true
|
Whether to delete the file after successfully reading it.
|
fileAge
|
long
|
no
|
disabled
|
Miniumum age (in ms) for a file to be processed. This can be useful when consuming large files. It tells Mule to wait for a period of time before consuming the file, allowing the file to be completely written before the file is processed.
WARNING: The fileAge attribute will only work properly if the servers where Mule and the sftp-server runs have synchronized time.
NOTE: See attribute sizeCheckWaitTime for an alternate method of determing if a incoming file is ready for processing.
|
sizeCheckWaitTime
|
long
|
no
|
disabled
|
Wait time (in ms) between size-checks to determine if a file is ready to be processed.
Disabled if not set or set to a negative value.
This feature can be useful to avoid processing not yet completely written files (e.g. consuming large files).
It tells Mule to do two size checks waiting the specified time between the two size calls.
If the two size calls return the same value Mule consider the file ready for processing.
NOTE: See attribute fileAge for an alternate method of determing if a incoming file is ready for processing.
|
archiveDir
|
string
|
no
|
disabled
|
Archives a copy of the file in the specified directory on the file system where mule is running.
The archive folder must have been created before Mule is started and the user Mule runs under must have privileges to read and write to the folder.
|
archiveTempReceivingDir
|
string
|
no
|
disabled
|
If specified then the file to be archived is received in this folder and then moved to the archiveTempSendingDir while sent further on to the outbound endpoint.
This folder is created as a subfolder to the archiveDir.
NOTE: Must be specified together with the archiveTempSendingDir and archiveDir attributes.
|
archiveTempSendingDir
|
string
|
no
|
disabled |
If specified then the file to be archived is sent to the outbound endpoint from this folder.
This folder is created as a subfolder to the archiveDir.
After the file is consumed by the outbound endpoint or the component itself (i.e. when the underlying InputStream is closed) it will be moved to the archive folder.
NOTE: Must be specified together with the archiveTempReceivingDir and archiveDir attributes.
|
| tempDir |
string |
no |
disabled |
A temporary directory on the ftp-server from where the download takes place.
The file will be moved (locally on the sftp-server) to the tempDir, to mark that a download is taking place, before the download starts.
NOTE: A file in the tempDir of an inbound endpoint is always correct (has only been moved locally on the sftp-server) and can therefore be used to restart a failing file transfer.
If specified then Mule tries to create the temp-directory in the endpoint folder if it doesn't already exist.
Ensure that the user Mule is configured to use to access the sftp server has privileges to create a temp folder if required!
|
| useTempFileTimestampSuffix |
boolean |
no |
false |
Used together with the tempDir - attribute to give the files in the tempDir a guaranteed unique name based on the local time when the file was moved to the tempDir.
|
Child elements of <sftp:inbound-endpoint> elements
SFTP Outbound Endpoint
SFTP specific attributes of <sftp:outbound-endpoint> elements
| Name |
Type |
Req. |
Default |
Description |
identityFile
|
string
|
no
|
disabled
|
An identityFile location for a PKI private key.
|
passphrase
|
string
|
no
|
disabled
|
The passphrase (password) for the identityFile if required.
|
| outputPattern |
string |
no |
the message id, e.g. ee241e68-c619-11de-986b-adeb3d6db038 |
The pattern to use when writing a file to disk.
This can use the patterns supported by the filename-parser configured for this connector, by default the [Legacy Filename Parser|http://www.mulesoft.org/display/MULE2USER/File+Transport#FileTransport-LegacyFilenameParser] is used.
NOTE: See section [Child Elements to File Connector|http://www.mulesoft.org/display/MULE2USER/File+Transport] for information on how to override the default parser.
|
keepFileOnError
|
boolean
|
no
|
true
|
If true the file on the inbound-endpoint will not be deleted if an error occurs when writing to the outbound-endpoint.
NOTE: This assumes that both the inbound and outbound endpoints are using the SFTP-Transport. |
duplicateHandling
|
enumeration:
- throwException
- overwrite
- addSeqNo
|
no
|
throwException |
Determines what to do if a file already exist on the outbound endpoint with the specified name:
- throwException: Will throw an exception if a file already exists
- overwrite: Will overwrite an existing file
- addSeqNo: Will add a sequence number to the target filename making the filename unique, starting with 1 and incrementing the number until a unique filename is found
|
| tempDir |
string |
no |
disabled |
A temporary directory on the sftp-server to first upload the file to. When the file is fully uploaded the file is moved to its final destination.
The tempDir will be created as a sub directory to the endpoint.
NOTE: A file in the tempDir of an outbound endpoint might not be correct (since the upload takes place to this folder) and can therefore NOT be used to restart a failing file transfer.
If specified then Mule tries to create the temp-directory in the endpoint folder if it doesn't already exist.
Ensure that the user Mule is configured to use to access the sftp server has privileges to create a temp folder if required!
|
| useTempFileTimestampSuffix |
boolean |
no |
false |
Used together with the tempDir - attribute to give the files in the tempDir a guaranteed unique name based on the local time when the file was moved to the tempDir. |
Streaming Payloads
The default payload for messages received from SFTP inbound endpoints is an SftpInputStream (which implements InputStream). When SftpInputStream is closed, the SFTP connection which supported the stream is also closed. Use the InputStreamByteArray transformer below if you are working with a small payload and prefer to not work with streams.
Messages sent to and SFTP outbound endpoint can be an InputStream, String, or byte[].
Transformers
THIS SECTION IS UNDER REVIEW
| Transformer |
Description |
org.mule.providers.sftp.transformers.InputStreamByteArray
|
Materializes an InputStream into a byte array |
This transformer makes it possible to use the SFTP Message Receiver with non-streaming Service Components or Message Dispatchers. Typical usage is to add this transformer to an SFTP receiving endpoint, so that downstream Service Components or Message Dispatchers can deal with a byte[] instead of InputStream. Note however that materializing an InputStream for a large file will cause OOM errors, so this transformer should not be used if large files are expected.
Functional Tests
THIS SECTION IS UNDER REVIEW
JUnit Class
|
Description |
org.mule.providers.sftp.LargeFileReceiveFunctionalTestCase
|
Tests ability of the SftpMessageReceiver to receive a large file. The file is received by a Service Component (ReceiveLargeFileTestHelperComponent) which streams the file to the /tmp directory.
|
| org.mule.providers.sftp.LargeFileSendFunctionalTestCase |
Tests ability of the SftpMessageDispatcher to send a large file. The file is streamed from /tmp/big.zip on the local machine.
|
| org.mule.providers.sftp.SendReceiveFunctionalTestCase |
Tests a round trip send/receive of multiple files. |
This page
Other pages
Account
Administration