Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.3)
  3. Reference Materials for Mule ESB 3
  4. Transports Reference

  5. FTP Transport Reference

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 messsages. 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. As of Mule 3, the SFTP Transport is included in the Mule distribution.

Transport Info

Transport Doc Inbound Outbound Request Transactions Streaming Retries MEPs Default MEP Maven Artifact

FTP

javaDocSchemaDoc

check

check

check

-

check

check

one-way

one-way

org.mule.transport:mule-transport-ftp

Legend:

Transport - The name/protocol of the transport
Docs - Links to the JavaDoc and SchemaDoc for the transport
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. For more information, see Streaming.
Retry - 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 - Message Exchange Patterns supported by this transport
Default MEP - The default MEP for endpoints that use this transport that do not explicitly configure a MEP
Maven Artifact - The group name a artifact name for this transport in linkhttp://maven.apache.org/[Maven]

Namespace and Syntax

Namespace (Community)

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

XML schema location (Community)

http://www.mulesoft.org/schema/mule/ftp/3.3/mule-ftp.xsd

Namespace (Enterprise)
Enterprise

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

XML schema location (Enterprise)
Enterprise

http://www.mulesoft.org/schema/mule/ee/ftp/3.3/mule-ftp-ee.xsd

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 to to filter 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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.3/mule-file.xsd
       http://www.mulesoft.org/schema/mule/ftp http://www.mulesoft.org/schema/mule/ftp/3.3/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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.3/mule-file.xsd
       http://www.mulesoft.org/schema/mule/ftp http://www.mulesoft.org/schema/mule/ftp/3.3/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: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/3.3/mule.xsd
       http://www.mulesoft.org/schema/mule/ftp http://www.mulesoft.org/schema/mule/ftp/3.3/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 will attempt 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 now 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 responsability of the user to close the input stream. If streaming is used on outbound endpoints Mule closes the stream automatically.

Configuration Reference

Element Listing

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 will use that connector.

Attributes of <connector…​>

Name Type Required Default Description

streaming

boolean

no

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

connectionFactoryClass

class name

no

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.

pollingFrequency

long

no

How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component.

outputPattern

string

no

The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector

binary

boolean

no

Select/disable binary file transfer type. Default is true.

passive

boolean

no

Select/disable passive protocol (more likely to work through firewalls). Default is true.

Child Elements of <connector…​>

Name Cardinality Description

file:abstract-filenameParser

0..1

The filenameParser is used when writing files to an FTP server. The parser will convert the outputPattern attribute to a string using the parser and the current message. To add a parser to your configuration, you 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 Type Required Default Description

path

string

no

A file location on the remote server.

user

string

no

If FTP is authenticated, this is the username used for authenitcation.

password

string

no

The password for the user being authenticated.

host

string

no

An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1).

port

port number

no

The port number to connect on.

binary

boolean

no

Select/disable binary file transfer type. Default is true.

passive

boolean

no

Select/disable passive protocol (more likely to work through firewalls). Default is true.

pollingFrequency

long

no

How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component.

Child Elements of <inbound-endpoint…​>

Name Cardinality Description

Outbound endpoint

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

path

string

no

A file location on the remote server.

user

string

no

If FTP is authenticated, this is the username used for authenitcation.

password

string

no

The password for the user being authenticated.

host

string

no

An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1).

port

port number

no

The port number to connect on.

binary

boolean

no

Select/disable binary file transfer type. Default is true.

passive

boolean

no

Select/disable passive protocol (more likely to work through firewalls). Default is true.

outputPattern

string

no

The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector

Child Elements of <outbound-endpoint…​>

Name Cardinality Description

Endpoint

Attributes of <endpoint…​>

Name Type Required Default Description

path

string

no

A file location on the remote server.

user

string

no

If FTP is authenticated, this is the username used for authenitcation.

password

string

no

The password for the user being authenticated.

host

string

no

An IP address (such as www.mulesoft.com, localhost, or 192.168.0.1).

port

port number

no

The port number to connect on.

binary

boolean

no

Select/disable binary file transfer type. Default is true.

passive

boolean

no

Select/disable passive protocol (more likely to work through firewalls). Default is true.

pollingFrequency

long

no

How frequently in milliseconds to check the read directory. Note that the read directory is specified by the endpoint of the listening component.

outputPattern

string

no

The pattern to use when writing a file to disk. This can use the patterns supported by the filename-parser configured for this connector

Child Elements of <endpoint…​>

Name Cardinality Description

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.3.1</version>
</dependency>

Enterprise

<dependency>
  <groupId>com.mulesoft.muleesb.transports</groupId>
  <artifactId>mule-transport-ftp-ee</artifactId>
  <version>3.3.1</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 that 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. It is an instance of:

ExpressionFilenameParser

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

It is possible to 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 that 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.