FTP Transport Reference

The FTP transport allows integration of the File Transfer Protocol into Mule. Mule can poll a remote FTP server directory, retrieve files. and process them as Mule messages. Messages can also be uploaded as files to a directory on a remote FTP server.

Mule also supports the SFTP protocol for secure file transfer. The SFTP Transport is included in the Mule distribution.

Transport Info

Feature	Value	Description
Transport	File	The name/protocol of the transport
Doc	JavaDoc, SchemaDoc	Javadoc and Schema doc
Inbound		Whether the transport can receive inbound events and can be used for an inbound endpoint.
Outbound		Whether the transport can produce outbound events and be used with an outbound endpoint.
Request		Whether this endpoint can be queried directly with a request call (via MuleClient or the EventContext).
Transactions		Whether transactions are supported by the transport. Transports that support transactions can be configured in either local or distributed two-phase commit (XA) transaction.
Streaming		Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data.
Retries		Whether this transport supports retry policies. Note that all transports can be configured with Retry policies, but only the ones marked here are officially supported by MuleSoft.
MEPs	one-way	Message Exchange Patterns supported by this transport.
Default MEP	one-way	The default MEP for endpoints that use this transport that do not explicitly configure a MEP
Maven Artifact	org.mule.transport:transportmule-transport-ftp	The group name and artifact name for this transport in Maven

Feature

Value

Description

Transport

File

The name/protocol of the transport

Doc

JavaDoc, SchemaDoc

Javadoc and Schema doc

Inbound

check

Whether the transport can receive inbound events and can be used for an inbound endpoint.

Outbound

check

Whether the transport can produce outbound events and be used with an outbound endpoint.

Request

check

Whether this endpoint can be queried directly with a request call (via MuleClient or the EventContext).

Transactions

error

Whether transactions are supported by the transport. Transports that support transactions can be configured in either local or distributed two-phase commit (XA) transaction.

Streaming

check

Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data.

Retries

check

Whether this transport supports retry policies. Note that all transports can be configured with Retry policies, but only the ones marked here are officially supported by MuleSoft.

MEPs

one-way

Message Exchange Patterns supported by this transport.

Default MEP

one-way

The default MEP for endpoints that use this transport that do not explicitly configure a MEP

Maven Artifact

org.mule.transport:transportmule-transport-ftp

The group name and artifact name for this transport in Maven

Namespace and Syntax

Namespace (Community):

http://www.mulesoft.org/schema/mule/ftp

XML schema location (Community):

http://www.mulesoft.org/schema/mule/ftp

Namespace (Enterprise)

Enterprise

http://www.mulesoft.org/schema/mule/ee/ftp

XML schema location (Enterprise)

Enterprise

http://www.mulesoft.org/schema/mule/ee/ftp

Syntax:

Straight URI example ftp://theUser:secret@theHost:port/path

XML version <ftp:endpoint host="theHost" port="22" path="/path" user="theUser" password="secret"/>

Connector and endpoint syntax <ftp:connector name="ftpConnector" passive="true" binary="true" streaming="true"/>

Considerations

Features

Poll a directory on a remote FTP server for new files
Retrieve files an FTP server
Transfer binary or text files
Filter files at the endpoint based on filename wildcards
Filter files at the endpoint based on Mule expressions
Upload and store files on an FTP server
Rename output files based on Mule expressions
Streaming for transferring large files
Support for reconnection strategies

Mule Enterprise includes several additional features that allow filtering of files to be processed by file age and moving and renaming files on the source FTP server after processing.

Usage

Each endpoint carries all the information for the FTP connection, such as, host, port, path, username and password at least. Additional properties (like binary or passive) can be specified on the connector and overridden at the endpoint level.

The FTP transport periodically polls the FTP server. Upon each poll request, a new connection to the FTP server is opened, the specified user is logged in and all files are listed under the specified path. This means that if the FTP server goes down no special provisions need to be made - the current poll attempt fails but polling doesn’t stop.

If reconnection strategies are configured, the FTP connection can be re-established automatically by Mule based on the policy you have configured.

The FTP transport does not support transactions as the File Transfer Protocol itself is not transactional. Instead you should design compensating transactions into your architecture using exception strategies in Mule.

Example Configurations

This example shows a simple flow that picks up all available files on the FTP server (in its root directory) and stores them into a directory on the local filesystem.

Downloading files from FTP using a Flow

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ftp="http://www.mulesoft.org/schema/mule/ftp"
       xmlns:file="http://www.mulesoft.org/schema/mule/file"
    xsi:schemaLocation="
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
       http://www.mulesoft.org/schema/mule/ftp http://www.mulesoft.org/schema/mule/ftp/current/mule-ftp.xsd">

    <flow name="ftp2file">
        <ftp:inbound-endpoint host="localhost" port="21" path="/" user="theUser" password="secret"/>
        <file:outbound-endpoint path="/some/directory" outputPattern="#[header:originalFilename]"/>
    </flow>
</mule>

This example shows how to pick only certain files on the FTP server. You do this by configuring filename filters to control which files the endpoint receives. The filters are expressed in a comma-separated list. Note that in order to use a filter from the file transport’s schema it must be included.

Filtering filenames using a Flow

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ftp="http://www.mulesoft.org/schema/mule/ftp"
       xmlns:file="http://www.mulesoft.org/schema/mule/file"
    xsi:schemaLocation="
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
       http://www.mulesoft.org/schema/mule/ftp http://www.mulesoft.org/schema/mule/ftp/current/mule-ftp.xsd">

    <flow name="fileFilter">
        <ftp:inbound-endpoint host="localhost" port="21" path="/" user="theUser" password="secret">
            <file:filename-wildcard-filter pattern="*.txt,*.xml"/>
        </ftp:inbound-endpoint>
        <file:outbound-endpoint path="/some/directory" outputPattern="#[header:originalFilename]"/>
    </flow>
</mule>

This example uses a simple-service to route files retrieved from the FTP server to MyProcessingComponent for further processing.

Processing a file from FTP

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ftp="http://www.mulesoft.org/schema/mule/ftp"
    xsi:schemaLocation="
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/ftp http://www.mulesoft.org/schema/mule/ftp/current/mule-ftp.xsd">

    <simple-service name="ftpProcessor"
                address="ftp://theUser:secret@host:21/"
                component-class="com.mycompany.mule.MyProcessingComponent"/>
</mule>

Configuration Options

Streaming

If streaming is not enabled on the FTP connector, Mule attempts to read a file it picks up from the FTP server into a byte[] to be used as the payload of the MuleMessage. This behavior can cause trouble if large files need to be processed.

In this case, enable streaming on the connector:

<ftp:connector name="ftpConnector" streaming="true">

Instead of reading the file’s content into memory, Mule sends an InputStream as the payload of the MuleMessage . The name of the file that this input stream represents is stored as the originalFilename property on the message. If streaming is used on inbound endpoints it is the responsibility of the user to close the input stream. If streaming is used on outbound endpoints Mule closes the stream automatically.

FTP Transport

The FTP transport provides connectivity to FTP servers to allow files to be read and written as messages in Mule.

Connector

The FTP connector is used to configure the default behavior for FTP endpoints that reference the connector. If there is only one FTP connector configured, all FTP endpoints use that connector.

Attributes of connector

Name Description

Name	Description
streaming	Whether an InputStream should be sent as the message payload (if true) or a byte array (if false). Default is false. Type: `boolean` Required: no Default: `false`
`connectionFactoryClass`	A class that extends FtpConnectionFactory. The FtpConnectionFactory is responsible for creating a connection to the server using the credentials provided by the endpoint. The default implementation supplied with Mule uses the Commons Net project from Apache. Type: `class name` Required: no Default: none
`pollingFrequency`	How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component. Type: `long` Required: no Default: none
`outputPattern`	The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector Type: `string` Required: no Default: none
`binary`	Select/disable binary file transfer type. Default is true. Type: `boolean` Required: no Default: `true`
`passive`	Select/disable passive protocol (more likely to work through firewalls). Default is true. Type: `boolean` Required: no Default: `true`

streaming

Whether an InputStream should be sent as the message payload (if true) or a byte array (if false). Default is false.
Type: boolean
Required: no
Default: false

connectionFactoryClass

A class that extends FtpConnectionFactory. The FtpConnectionFactory is responsible for creating a connection to the server using the credentials provided by the endpoint. The default implementation supplied with Mule uses the Commons Net project from Apache.
Type: class name
Required: no
Default: none

pollingFrequency

How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component.
Type: long
Required: no
Default: none

outputPattern

The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector
Type: string
Required: no
Default: none

binary

Select/disable binary file transfer type. Default is true.
Type: boolean
Required: no
Default: true

passive

Select/disable passive protocol (more likely to work through firewalls). Default is true.
Type: boolean
Required: no
Default: true

Child Elements of connector

Name Cardinality Description

Name	Cardinality	Description
`file:abstract-filenameParser`	0..1	The filenameParser is used when writing files to an FTP server. The parser converts the outputPattern attribute to a string using the parser and the current message. To add a parser to your configuration, import the "file" namespace into your XML configuration. For more information about filenameParsers, see the File Transport Reference.

file:abstract-filenameParser

0..1

The filenameParser is used when writing files to an FTP server. The parser converts the outputPattern attribute to a string using the parser and the current message. To add a parser to your configuration, import the "file" namespace into your XML configuration. For more information about filenameParsers, see the File Transport Reference.

Inbound Endpoint

Attributes of inbound-endpoint

Name Description

Name	Description
`path`	A file location on the remote server. Type: `string` Required: no Default: none
`user`	If FTP is authenticated, this is the username used for authentication. Type: `string` Required: no Default: none
`password`	The password for the user being authenticated. Type: `string` Required: no Default: none
`host`	An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1). Type: `string` Required: no Default: none
`port`	The port number to connect on. Type: `port number` Required: no Default: none
`binary`	Select/disable binary file transfer type. Default is true. Type: `boolean` Required: no Default: `true`
`passive`	Select/disable passive protocol (more likely to work through firewalls). Default is true. Type: `boolean` Required: no Default: `true`
`pollingFrequency`	How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component. Type: `long` Required: no Default: none

path

A file location on the remote server.
Type: string
Required: no
Default: none

user

If FTP is authenticated, this is the username used for authentication.
Type: string
Required: no
Default: none

password

The password for the user being authenticated.
Type: string
Required: no
Default: none

host

An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1).
Type: string
Required: no
Default: none

port

The port number to connect on.
Type: port number
Required: no
Default: none

binary

Select/disable binary file transfer type. Default is true.
Type: boolean
Required: no
Default: true

passive

Select/disable passive protocol (more likely to work through firewalls). Default is true.
Type: boolean
Required: no
Default: true

pollingFrequency

How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component.
Type: long
Required: no
Default: none

No child elements for inbound-endpoint

Outbound Endpoint

Attributes of outbound-endpoint

Name

Description

path

A file location on the remote server.
Type: string
Required: no
Default: none

user

If FTP is authenticated, this is the username used for authentication.
Type: string
Required: no
Default: none

password

The password for the user being authenticated.
Type: string
Required: no
Default: none

host

An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1).
Type: string
Required: no
Default: none

port

The port number to connect on.
Type: port number
Required: no
Default: none

binary

elect/disable binary file transfer type. Default is true.
Type: boolean
Required: no
Default: true

passive

Select/disable passive protocol (more likely to work through firewalls). Default is true.
Type: boolean
Required: no
Default: true

outputPattern

The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector.
Type: string
Required: no
Default: none

No child elements for outbound-endpoint

Endpoint

Attributes of endpoint

Name Description

Name	Description
path	A file location on the remote server. Type: `string` Required: no Default: none
user	If FTP is authenticated, this is the username used for authentication. Type: `string` Required: no Default: none
password	The password for the user being authenticated. Type: `string` Required: no Default: none
`host`	An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1). Type: `string` Required: no Default: none
`port`	The port number to connect on. Type: `port number` Required: no Default: none
`binary`	Select/disable binary file transfer type. Default is true. Type: `boolean` Required: no Default: `true`
`passive`	Select/disable passive protocol (more likely to work through firewalls). Default is true. Type: `boolean` Required: no Default: `true`
`pollingFrequency`	How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component. Type: `long` Required: no Default: none
`outputPattern`	The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector. Type: `string` Required: no Default: none

path

A file location on the remote server.
Type: string
Required: no
Default: none

user

If FTP is authenticated, this is the username used for authentication.
Type: string
Required: no
Default: none

password

The password for the user being authenticated.
Type: string
Required: no
Default: none

host

An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1).
Type: string
Required: no
Default: none

port

The port number to connect on.
Type: port number
Required: no
Default: none

binary

Select/disable binary file transfer type. Default is true.
Type: boolean
Required: no
Default: true

passive

Select/disable passive protocol (more likely to work through firewalls). Default is true.
Type: boolean
Required: no
Default: true

pollingFrequency

How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component.
Type: long
Required: no
Default: none

outputPattern

The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector.
Type: string
Required: no
Default: none

No child elements for endpoint.

Mule Enterprise Connector Attributes

Enterprise

The following additional attributes are available on the FTP connector in Mule Enterprise only:

moveToDirectory

The directory path where the file should be written after it has been read. If this property is not set, the file is deleted.

moveToPattern

The pattern to use when moving a read file to a new location as specified by the moveToDirectory property. This property can use the patterns supported by the filenameParser configured for this connector.

fileAge

Do not process the file unless it’s older than the specified age in milliseconds.

Schema

Complete schema reference documentation.

Javadoc API Reference

Javadoc for FTP Transport

Maven

The FTP transport can be included with the following dependency:

Community

<dependency>
  <groupId>org.mule.transports</groupId>
  <artifactId>mule-transport-ftp</artifactId>
  <version>3.8.0</version>
</dependency>

Enterprise

<dependency>
  <groupId>com.mulesoft.muleesb.transports</groupId>
  <artifactId>mule-transport-ftp-ee</artifactId>
  <version>3.8.0</version>
</dependency>

Extending this Module or Transport

Custom FtpConnectionFactory

The FtpConnectionFactory establishes Mule’s connection to the FTP server. The default connection factory should be sufficient in 99% of the cases. If you need to change the way Mule connects to your FTP server use the connectionFactoryClass attribute on the connector:

<ftp:connector name="ftpConnector" connectionFactoryClass="com.mycompany.mule.MyFtpConnectionFactory"/>

Use the fully qualified class name of your FtpConnectionFactory subclass.

Note: This must be a subclass of FtpConnectionFactory as the FtpConnector attempts to cast the factory to that class.

Filename Parser

The filenameParser is used when writing files to the FTP server. The parser converts the output pattern configured on an endpoint to the name of the file that is written using the parser and the current message.

The filename parser used in the FTP transport should be sufficient in 99% of the cases. The parser is an instance of:

ExpressionFilenameParser

Which allows to use arbitrary expressions to compose the filename that is used when storing files on the FTP server.

You can configure a custom filename parser as a child element of the connector declaration:

<ftp:connector name="ftpConnector" passive="true" binary="true" streaming="true">
    <file:custom-filename-parser class="com.mycompany.mule.MyFilenameParser"/>
</ftp:connector>

Note: The class you configure here must implement the FilenameParser interface.

Best Practices

Put your login credentials in a properties file, not hard-coded in the configuration. This also allows you to use different settings between development, test, and production systems.