Access Keys:
Skip to content (Access Key - 0)
Cancel    
Cancel   

Contents

FTP Transport Reference

Introduction

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

 

TransportDocInboundOutboundRequestTransactionsStreamingRetriesMEPsDefault MEPMaven Artifact
FTP JavaDoc
SchemaDoc
one-wayone-wayorg.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 MuleClinet 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 Maven

Namespace and Syntax

Namespace (Community edition)

XML schema location (Community Edition)

Namespace (Enterprise edition)
Enterprise Edition

XML schema location (Enterprise Edition)
Enterprise Edition

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

The Mule Enterprise Edition 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, i.e. 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 will fail but polling will not be stopped.

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

 

 

 

 

Downloading files from FTP using a Flow

 

 

 

 

 

 

  

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.

 

 

 

 

Filtering filenames using a Flow

 

 

 

 

 

 

  

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.

Processing a file from FTP

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

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 behaviour can cause trouble if large files need to be processed.

In this case, enable streaming on the connector:

Instead of reading the file's content into memory Mule will now send 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

name

name (no spaces)

yes

 

Identifies the connector so that other elements can reference it.

name

name (no spaces)

yes

 

Identifies the connector so that other elements can reference it.

dynamicNotification

boolean

no

false

Enables dynamic notifications for notifications fired by this connector. This allows listeners to be registered dynamically at runtime via the MuleContext, and the configured notification can be changed. This overrides the default value defined in the 'configuration' element.

validateConnections

boolean

no

true

Causes Mule to validate connections before use. Note that this is only a configuration hint, transport implementations may or may not make an extra effort to validate the connection. Default is true.

dispatcherPoolFactory-ref

string

no

 

Allows Spring beans to be defined as a dispatcher pool factory

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

spring:property

0..*

 

receiver-threading-profile

0..1

The threading profile to use when a connector receives messages.

dispatcher-threading-profile

0..1

The threading profile to use when a connector dispatches messages.

abstract-reconnection-strategy

0..1

Reconnection strategy that defines how Mule should handle a connection failure. A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

service-overrides

0..1

Service overrides allow the connector to be further configured/customized by allowing parts of the transport implementation to be overridden, for example, the message receiver or dispatcher implementation, or the message adaptor that is used.

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

name

name (no spaces)

no

 

Identifies the endpoint in the registry. There is no need to set the 'name' attribute on inbound or outbound endpoints, only on global endpoints.

name

name (no spaces)

no

 

Identifies the endpoint in the registry. There is no need to set the 'name' attribute on inbound or outbound endpoints, only on global endpoints.

ref

string

no

 

A reference to a global endpoint, which is used as a template to construct this endpoint. A template fixes the address (protocol, path, host, etc.), and may specify initial values for various properties, but further properties can be defined locally (as long as they do not change the address in any way).

address

string

no

 

The generic address for this endpoint. If this attribute is used, the protocol must be specified as part of the URI. Alternatively, most transports provide their own attributes for specifying the address (path, host, etc.). Note that the address attribute cannot be combined with 'ref' or with the transport-provided alternative attributes.

responseTimeout

integer

no

 

The timeout for a response if making a synchronous endpoint call

encoding

string

no

 

String encoding used for messages.

connector-ref

string

no

 

The name of the connector associated with this endpoint. This must be specified if more than one connector is defined for this transport.

transformer-refs

list of names

no

 

A list of the transformers that will be applied (in order) to the message before it is delivered to the component.

responseTransformer-refs

list of names

no

 

A list of the transformers that will be applied (in order) to the synchronous response before it is returned via the transport.

disableTransportTransformer

boolean

no

 

Don't use the default inbound/outbound/response transformer which corresponds to this endpoint's transport, if any.

mimeType

string

no

 

The mime type, e.g. text/plain or application/json

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

response

0..1

 

abstract-transaction

0..1

A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.

abstract-reconnection-strategy

0..1

A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

abstract-multi-transaction

0..1

A placeholder for multi-transaction elements. Multi-transactions allow a series of operations to be grouped together spanning different transports, e.g. JMS and JDBC, but without the overhead of XA. The trade-off is that XA reliability guarantees aren't available, and services must be ready to handle duplicates. This is very similar to a 1.5 PC concept. EE-only feature.

abstract-transformer

0..1

A placeholder for transformer elements. Transformers convert message payloads.

abstract-filter

0..1

A placeholder for filter elements, which control which messages are handled.

abstract-security-filter

0..1

A placeholder for security filter elements, which control access to the system.

abstract-intercepting-message-processor

0..1

A placeholder for intercepting router elements.

abstract-observer-message-processor

0..1

A placeholder for message processors that observe the message but do not mutate it used for exmaple for logging.

processor

0..1

A reference to a message processor defined elsewhere.

custom-processor

0..1

 

property

0..*

Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which provide a generic way of configuring the system. Typically, you shouldn't need to use a generic property like this, since almost all functionality is exposed via dedicated elements. However, it can be useful in configuring obscure or overlooked options and in configuring transports from the generic endpoint elements.

properties

0..1

A map of Mule properties.

Outbound endpoint

Attributes of <outbound-endpoint...>

Name

Type

Required

Default

Description

name

name (no spaces)

no

 

Identifies the endpoint in the registry. There is not need to set the 'name' attribute on inbound or outbound endpoints, only on global endpoints.

name

name (no spaces)

no

 

Identifies the endpoint in the registry. There is not need to set the 'name' attribute on inbound or outbound endpoints, only on global endpoints.

ref

string

no

 

A reference to a global endpoint, which is used as a template to construct this endpoint. A template fixes the address (protocol, path, host, etc.), and may specify initial values for various properties, but further properties can be defined locally (as long as they do not change the address in any way).

address

string

no

 

The generic address for this endpoint. If this attribute is used, the protocol must be specified as part of the URI. Alternatively, most transports provide their own attributes for specifying the address (path, host, etc.). Note that the address attribute cannot be combined with 'ref' or with the transport-provided alternative attributes.

responseTimeout

integer

no

 

The timeout for a response if making a synchronous endpoint call

encoding

string

no

 

String encoding used for messages.

connector-ref

string

no

 

The name of the connector associated with this endpoint. This must be specified if more than one connector is defined for this transport.

transformer-refs

list of names

no

 

A list of the transformers that will be applied (in order) to the message before it is delivered to the component.

responseTransformer-refs

list of names

no

 

A list of the transformers that will be applied (in order) to the synchronous response before it is returned via the transport.

disableTransportTransformer

boolean

no

 

Don't use the default inbound/outbound/response transformer which corresponds to this endpoint's transport, if any.

mimeType

string

no

 

The mime type, e.g. text/plain or application/json

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

response

0..1

 

abstract-transaction

0..1

A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.

abstract-reconnection-strategy

0..1

A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

abstract-multi-transaction

0..1

A placeholder for multi-transaction elements. Multi-transactions allow a series of operations to be grouped together spanning different transports, e.g. JMS and JDBC, but without the overhead of XA. The trade-off is that XA reliability guarantees aren't available, and services must be ready to handle duplicates. This is very similar to a 1.5 PC concept. EE-only feature.

abstract-transformer

0..1

A placeholder for transformer elements. Transformers convert message payloads.

abstract-filter

0..1

A placeholder for filter elements, which control which messages are handled.

abstract-security-filter

0..1

A placeholder for security filter elements, which control access to the system.

abstract-intercepting-message-processor

0..1

A placeholder for intercepting router elements.

abstract-observer-message-processor

0..1

A placeholder for message processors that observe the message but do not mutate it used for exmaple for logging.

processor

0..1

A reference to a message processor defined elsewhere.

custom-processor

0..1

 

property

0..*

Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which provide a generic way of configuring the system. Typically, you shouldn't need to use a generic property like this, since almost all functionality is exposed via dedicated elements. However, it can be useful in configuring obscure or overlooked options and in configuring transports from the generic endpoint elements.

properties

0..1

A map of Mule properties.

Endpoint

Attributes of <endpoint...>

Name

Type

Required

Default

Description

name

name (no spaces)

yes

 

Identifies the endpoint so that other elements can reference it. This name can also be referenced in the MuleClient.

name

name (no spaces)

yes

 

Identifies the endpoint so that other elements can reference it. This name can also be referenced in the MuleClient.

ref

string

no

 

A reference to a global endpoint, which is used as a template to construct this endpoint. A template fixes the address (protocol, path, host, etc.), and may specify initial values for various properties, but further properties can be defined locally (as long as they do not change the address in any way).

address

string

no

 

The generic address for this endpoint. If this attribute is used, the protocol must be specified as part of the URI. Alternatively, most transports provide their own attributes for specifying the address (path, host, etc.). Note that the address attribute cannot be combined with 'ref' or with the transport-provided alternative attributes.

responseTimeout

integer

no

 

The timeout for a response if making a synchronous endpoint call

encoding

string

no

 

String encoding used for messages.

connector-ref

string

no

 

The name of the connector associated with this endpoint. This must be specified if more than one connector is defined for this transport.

transformer-refs

list of names

no

 

A list of the transformers that will be applied (in order) to the message before it is delivered to the component.

responseTransformer-refs

list of names

no

 

A list of the transformers that will be applied (in order) to the synchronous response before it is returned via the transport.

disableTransportTransformer

boolean

no

 

Don't use the default inbound/outbound/response transformer which corresponds to this endpoint's transport, if any.

mimeType

string

no

 

The mime type, e.g. text/plain or application/json

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

response

0..1

 

abstract-transaction

0..1

A placeholder for transaction elements. Transactions allow a series of operations to be grouped together.

abstract-reconnection-strategy

0..1

A placeholder for a reconnection strategy element. Reconnection strategies define how Mule should attempt to handle a connection failure.

abstract-multi-transaction

0..1

A placeholder for multi-transaction elements. Multi-transactions allow a series of operations to be grouped together spanning different transports, e.g. JMS and JDBC, but without the overhead of XA. The trade-off is that XA reliability guarantees aren't available, and services must be ready to handle duplicates. This is very similar to a 1.5 PC concept. EE-only feature.

abstract-transformer

0..1

A placeholder for transformer elements. Transformers convert message payloads.

abstract-filter

0..1

A placeholder for filter elements, which control which messages are handled.

abstract-security-filter

0..1

A placeholder for security filter elements, which control access to the system.

abstract-intercepting-message-processor

0..1

A placeholder for intercepting router elements.

abstract-observer-message-processor

0..1

A placeholder for message processors that observe the message but do not mutate it used for exmaple for logging.

processor

0..1

A reference to a message processor defined elsewhere.

custom-processor

0..1

 

property

0..*

Sets a Mule property. This is a name/value pair that can be set on components, services, etc., and which provide a generic way of configuring the system. Typically, you shouldn't need to use a generic property like this, since almost all functionality is exposed via dedicated elements. However, it can be useful in configuring obscure or overlooked options and in configuring transports from the generic endpoint elements.

properties

0..1

A map of Mule properties.

Mule Enterprise Connector Attributes

Enterprise Edition

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 edition

Enterprise edition
Enterprise Edition

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:

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 will convert the output pattern configured on an endpoint to the name of the file that will be 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 to use arbitrary expressions to compose the filename that is used when storing files on the FTP server.

It is possible to configure a custom filename parser as a child element of the connector declaration:

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.