Contact Free trial Login

FTP Connector Reference - Mule 4

Support Category: Select FTP Connector v1.4

The FTP Connector connects to the specified FTP server.

Configurations


Default Configuration

Parameters

Name Type Description Default Value Required

Name

String

The name for this configuration. Connectors reference the configuration with this name.

x

Connection

The connection types to provide to this configuration.

x

Default write encoding (DEPRECATED)

String

This parameter is deprecated and is ignored.

Time Between Size Check

Number

When enabled, Mule performs two size checks, waiting the specified time between calls. If both checks return the same value, the file is ready to be read. This allows a file write to complete before the file is processed. This attribute works in tandem with *Time between size check unit*. If no value is provided, the check is not performed.

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A Time unit that qualifies the Time between size check attribute. Defaults to MILLISECONDS.

MILLISECONDS

Expiration Policy

Configures the minimum amount of time that a dynamic configuration instance can remain idle before the runtime considers it eligible for expiration. This does not mean that the platform expires the instance at the exact moment that it becomes eligible. The runtime purges the instances when as appropriate.

Connection Types

FTP Connection

Connects to an FTP server.

Parameters
Name Type Description Default Value Required

Working Directory

String

The directory designated as the root of every relative path used with this connector. If not provided, it defaults to the remote server default.

Transfer Mode

Enumeration, one of:

  • BINARY

  • ASCII

The transfer mode to use. Currently, BINARY (default) and ASCII are supported.

BINARY

Passive

Boolean

Whether to use passive mode. Set to false to switch to active mode.

true

Enable Remote Verification

Boolean

Enable or disable verification that the remote host taking part of a data connection is the same as the host to which the control connection is attached.

true

Connection Timeout

Number

A scalar value representing the amount of time to wait before a connection attempt times out. This attribute works in tandem with Connection timeout unit.

10

Connection Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A Time unit that qualifies the Connection timeout attribute.

SECONDS

Response Timeout

Number

A scalar value representing the amount of time to wait before a request for data times out. This attribute works in tandem with Response timeout unit.

10

Response Timeout Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A Time unit that qualifies the Response timeout unit attribute.

SECONDS

Host

String

The FTP server host, such as www.mulesoft.com, localhost, or 192.168.0.1, and so on.

x

Port

Number

The port number of the FTP server to which to connect.

21

Username

String

Username for the FTP Server. Required if the server is authenticated.

Password

String

Password for the FTP Server. Required if the server is authenticated.

Reconnection

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Pooling Profile

Characteristics of the connection pool.

Operations

Associated Sources

Copy

<ftp:copy>

Copies the file or directory specified in Source Path into the Target Path. The source path can be either a file or a directory. If it points to a directory, then it is copied recursively.

If the target path doesn’t exist, and neither does its parent, then a parent folder is created if Create parent directories is set to true. If Create parent directories is set to false, then an FTP:ILLEGAL_PATH error is thrown.

If Overwrite is set to true and the target file already exists, then the target file is overwritten. Otherwise, an FTP:FILE_ALREADY_EXISTS error is thrown.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Source Path

String

The path to the file to be copied.

x

Target Path

String

The target directory where the file is going to be copied.

x

Create Parent Directories

Boolean

Whether or not to attempt creating any parent directories that don’t exist.

true

Overwrite

Boolean

Whether or not to overwrite the file if the target destination already exists.

false

Rename To

String

The new name for the copied file. If not provided, original file name is kept.

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • FTP:FILE_ALREADY_EXISTS

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:CONNECTIVITY

Create Directory

<ftp:create-directory>

Creates a new directory on Directory path.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Directory Path

String

The name for the new directory.

x

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • FTP:FILE_ALREADY_EXISTS

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:ACCESS_DENIED

  • FTP:CONNECTIVITY

Delete

<ftp:delete>

Deletes the file that is pointed to by the path, provided the file isn’t locked.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Path

String

The path to the file to delete.

x

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:ACCESS_DENIED

  • FTP:CONNECTIVITY

List

<ftp:list>

Lists all the files in the Directory path that match the given matcher. If the listing encounters a directory, the output list will include its contents, depending on the value of the recursive parameter.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Directory Path

String

The path to the directory to list.

x

Recursive

Boolean

Whether to include the contents of subdirectories.

false

File Matching Rules

A matcher used to filter the output list.

Time Between Size Check

Number

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Streaming Strategy

Configure to use repeatable streams.

Target Variable

String

The name of a variable to store the operation’s output.

Target Value

String

An expression to evaluate against the operation’s output and then store the expression’s outcome in the target variable.

#[payload]

Reconnection Strategy

A retry strategy in case of connectivity errors.

Output

Type

Array of Message of payload and [Ftp File Attributes] attributes.

For Configurations

Throws

  • FTP:ILLEGAL_PATH

  • FTP:ACCESS_DENIED

Move

<ftp:move>

Moves the file or directory from the Source Path into the Target Path. The source path can be either a file or a directory. If it points to a directory, then it will be moved recursively.

If the target path doesn’t exist, and neither does its parent, then a parent folder is created if Create parent directories is set to true. If Create parent directories is set to false, then an FTP:ILLEGAL_PATH error is thrown.

If the target file already exists, then it will be overwritten if Overwrite is set to true. If Overwrite is set to false, an FTP:FILE_ALREADY_EXISTS error will be thrown.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Source Path

String

The path to the file to be copied.

x

Target Path

String

The target directory.

x

Create Parent Directories

Boolean

Whether or not to attempt creating any parent directories that don’t exist.

true

Overwrite

Boolean

Whether or not to overwrite the file if the target destination already exists.

false

Rename To

String

The new name for the moved file. If not provided, the original file name is kept.

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • FTP:FILE_ALREADY_EXISTS

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:CONNECTIVITY

Read

<ftp:read>

Obtains the content and metadata of a file at a specified path. The operation itself returns a Message with a payload that is an input stream with the file’s content, and the metadata is represented as an FtpFileAttributes object that’s placed as the message’s Message#getAttributes() attributes.

If the lock parameter is set to true, then a file system-level lock is placed on the file until the input stream this operation returns is closed or fully consumed. Because the lock is actually provided by the host file system, its behavior might change depending on the mounted drive and the operation system on which Mule is running. Take that into consideration before relying on this lock.

This method also makes a best effort to determine the MIME type of the file being read by using the file’s extension to make an educated guess. You can also use the output Encoding and output MIME Type optional parameters to force the encoding and MIME type.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

File Path

String

The path to the file to be read.

x

Lock

Boolean

Whether or not to lock the file.

false

Time Between Size Check

Number

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

Output Mime Type

String

The MIME type of the payload that this operation outputs.

Output Encoding

String

The encoding of the payload that this operation outputs.

Streaming Strategy

Configure to use repeatable streams.

Target Variable

String

The name of a variable to store the operation’s output.

Target Value

String

An expression to evaluate against the operation’s output and store the expression outcome in the target variable.

#[payload]

Reconnection Strategy

A retry strategy in case of connectivity errors.

Output

Type

Binary

Attributes Type

For Configurations

Throws

  • FTP:FILE_LOCK

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:ACCESS_DENIED

  • FTP:CONNECTIVITY

Rename

<ftp:rename>

Renames the file to which the path points to the value provided in the New Name parameter. This argument should not contain any path separator, or an FTP:ILLEGAL_PATH error will be thrown.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Path

String

The path to the file to be renamed.

x

New Name

String

The file’s new name.

x

Overwrite

Boolean

Whether or not to overwrite the file if the target destination already exists.

false

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • FTP:FILE_ALREADY_EXISTS

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:ACCESS_DENIED

  • FTP:CONNECTIVITY

Write

<ftp:write>

Writes the content into the file the path points to.

If the directory to which the file is attempting to be written doesn’t exist, then the operation will either throw an FTP:ILLEGAL_PATH error, or create a new folder, depending on the value of Create parent directories. If the file already exists, then the behavior depends on the supplied mode.

This operation also supports locking depending on the value of the lock argument, and follows the same rules and considerations as described in the read operation.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Path

String

The path of the file to be written to.

x

Content

Binary

The content to be written into the file. Defaults to the current Message payload.

#[payload]

Encoding (DEPRECATED)

String

When content is a String, this attribute specifies the encoding to use when writing. If not set, then it defaults to FileConnectorConfig#getDefaultWriteEncoding().

Create Parent Directories

Boolean

Whether or not to attempt creating any parent directories that don’t exist.

true

Lock

Boolean

Whether or not to lock the file.

false

Write Mode

Enumeration, one of:

  • OVERWRITE

  • APPEND

  • CREATE_NEW

A file Write Mode.

OVERWRITE

Reconnection Strategy

A retry strategy in case of connectivity errors.

For Configurations

Throws

  • FTP:FILE_LOCK

  • FTP:ILLEGAL_CONTENT

  • FTP:FILE_ALREADY_EXISTS

  • FTP:RETRY_EXHAUSTED

  • FTP:ILLEGAL_PATH

  • FTP:ACCESS_DENIED

  • FTP:CONNECTIVITY

Sources

On New or Updated File

<ftp:listener>

Polls a directory and looks for files that have been created in it. One message is generated for each file that is found.

The key part of this functionality is how to determine that a file is actually new. There are three strategies for that:

  • Set the Auto delete parameter to true to delete each file after it is processed, which causes all files obtained in the next poll to be necessarily new.

  • Set the Move to directory parameter to move each file to a different directory after it is processed, which achieves the same effect as Auto delete but without losing the file.

  • Use Watermark enabled to pick only files that have been created or updated after the last poll was executed.

You can also use a matcher for additional filtering of files.

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x

Directory

String

The directory that contains polled files.

Recursive

Boolean

Whether or not to also poll files contained in subdirectories.

true

Matcher

A matcher used to filter events on files that do not meet the matcher’s criteria.

Watermark Enabled

Boolean

Controls whether or not to do watermarking, and if so, if the watermark should consider the file’s modification or creation timestamps.

false

Time Between Size Check

Number

Wait time (in milliseconds) between size checks to determine if a file is ready to be read. This allows a file write to complete before processing. You can disable this feature by omitting a value. When enabled, Mule performs two size checks, waiting the specified time between calls. If both checks return the same value, the file is ready to be read.

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A Time unit that qualifies the Time between size check attribute.

Output Mime Type

String

The MIME type of the payload that this operation outputs.

Output Encoding

String

The encoding of the payload that this operation outputs.

Primary Node Only

Boolean

Whether this source should be executed only on the primary node when running in a Cluster.

Scheduling Strategy

scheduling-strategy

Configures the scheduler that triggers the polling.

x

Streaming Strategy

Configure to use repeatable streams.

Redelivery Policy

Defines a policy for processing the redelivery of the same message.

Reconnection Strategy

A retry strategy in case of connectivity errors.

Auto Delete

Boolean

Whether or not each file should be deleted after processing.

false

Move To Directory

String

If provided, each processed file will be moved to a directory pointed to by this path.

Rename To

String

This parameter works in tandem with Move to directory. Use this parameter to enter the name under which the file should be moved. Do not set this parameter if Move to directory hasn’t been set as well.

Apply Post Action When Failed

Boolean

Whether any of the post actions (autoDelete and moveToDirectory) should also be applied in case the file failed to be processed. If set to false, no failed files will be moved or deleted.

true

Output

Type

Binary

Attributes Type

For Configurations

Types

Reconnection

Field Type Description Default Value Required

Fails Deployment

Boolean

When the application is deployed, a connectivity test is performed on all connectors. If set to true, deployment fails if the test doesn’t pass after exhausting the associated reconnection strategy.

Reconnection Strategy

The reconnection strategy to use.

Reconnect

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

Count

Number

How many reconnection attempts to make.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

Reconnect Forever

Field Type Description Default Value Required

Frequency

Number

How often in milliseconds to reconnect.

blocking

Boolean

If false, the reconnection strategy runs in a separate, non-blocking thread.

true

Pooling Profile

Field Type Description Default Value Required

Max Active

Number

Controls the maximum number of Mule components that can be borrowed from a session at one time. When set to a negative value, there is no limit to the number of components that can be active at one time. When maxActive is exceeded, the pool is said to be exhausted.

Max Idle

Number

Controls the maximum number of Mule components that can sit idle in the pool at any time. When set to a negative value, there is no limit to the number of Mule components that can be idle at one time.

Max Wait

Number

Specifies the number of milliseconds to wait for a pooled component to become available when the pool is exhausted and the Exhausted action is set to WHEN_EXHAUSTED_WAIT.

Min Eviction Millis

Number

Determines the minimum amount of time an object can sit idle in the pool before it is eligible for eviction. When non-positive, no objects will be evicted from the pool due to idle time alone.

Eviction Check Interval Millis

Number

Specifies the number of milliseconds between runs of the object evictor. When non-positive, no object evictor is executed.

Exhausted Action

Enumeration, one of:

  • WHEN_EXHAUSTED_GROW

  • WHEN_EXHAUSTED_WAIT

  • WHEN_EXHAUSTED_FAIL

Specifies the behavior of the Mule component pool when the pool is exhausted. Possible values are:

  • WHEN_EXHAUSTED_FAIL
    Throws a NoSuchElementException.

  • WHEN_EXHAUSTED_WAIT
    Blocks by invoking Object.wait(long) until a new or idle object is available.

  • WHEN_EXHAUSTED_GROW
    Creates a new Mule instance and returns it, essentially making Max active meaningless.

If a positive Max wait value is supplied, it will block for that many milliseconds at most, after which a NoSuchElementException will be thrown. If maxThreadWait is a negative value, it will block indefinitely.

Initialisation Policy

Enumeration, one of:

  • INITIALISE_NONE

  • INITIALISE_ONE

  • INITIALISE_ALL

Determines how components in a pool should be initialized. The possible values are:

  • INITIALISE_NONE
    Will not load any components into the pool on startup.

  • INITIALISE_ONE
    Will load one initial component into the pool on startup.

  • INITIALISE_ALL
    Will load all components in the pool on startup.

Disabled

Boolean

Whether pooling should be disabled.

Expiration Policy

Field Type Description Default Value Required

Max Idle Time

Number

A scalar time value for the maximum amount of time a dynamic configuration instance should be allowed to be idle before it’s considered eligible for expiration.

Time Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A time unit that qualifies the maxIdleTime attribute.

Ftp File Attributes

Field Type Description Default Value Required

Timestamp

DateTime

Name

String

x

Size

Number

x

Regular File

Boolean

false

Directory

Boolean

false

Symbolic Link

Boolean

false

Path

String

x

File Name

String

x

Matcher

Field Type Description Default Value Required

Timestamp Since

DateTime

Files created before this date are rejected. If no creation date is available, the file will be processed.

Timestamp Until

DateTime

Files created after this date are rejected. If no creation date is available, the file will be processed.

Not Updated In The Last

Number

Minimum time that should pass since a file was updated in order for it to not be rejected. This attribute works in tandem with #timeUnit.

Updated In The Last

Number

Maximum time that should pass since a file was updated in order to not be rejected. This attribute works in tandem with #timeUnit.

Time Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A #notUpdatedInTheLast attributes.

Defaults to SECONDS

SECONDS

Filename Pattern

String

Path Pattern

String

Directories

Enumeration, one of:

  • REQUIRE

  • INCLUDE

  • EXCLUDE

INCLUDE

Regular Files

Enumeration, one of:

  • REQUIRE

  • INCLUDE

  • EXCLUDE

INCLUDE

Sym Links

Enumeration, one of:

  • REQUIRE

  • INCLUDE

  • EXCLUDE

INCLUDE

Min Size

Number

Max Size

Number

Repeatable In Memory Stream

Field Type Description Default Value Required

Initial Buffer Size

Number

The amount of memory to allocate to consume the stream and provide random access to it. If the stream contains more data than can be fit into this buffer, then the buffer expands according to the Buffer size increment attribute, with an upper limit of maxInMemorySize.

Buffer Size Increment

Number

This is by how much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower means that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised when the buffer gets full.

Max Buffer Size

Number

The maximum amount of memory to use. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower than, or equal to, zero means no limit.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which all these attributes are expressed.

Repeatable File Store Stream

Field Type Description Default Value Required

In Memory Size

Number

Defines the maximum memory that the stream should use to keep data in memory. If more than that is consumed then it will start to buffer the content on disk.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which maxInMemorySize is expressed.

Redelivery Policy

Field Type Description Default Value Required

Max Redelivery Count

Number

The maximum number of times a message can be redelivered and processed unsuccessfully before triggering a process-failed-message.

Use Secure Hash

Boolean

Whether to use a secure hash algorithm to identify a redelivered message.

Message Digest Algorithm

String

The secure hashing algorithm to use. If not set, the default is SHA-256.

SHA-256

Id Expression

String

Defines one or more expressions to use to determine when a message has been redelivered. This property may only be set if Use secure hash is false.

Object Store

Object Store

The object store where the redelivery counter for each message is going to be stored.

Repeatable In Memory Iterable

Field Type Description Default Value Required

Initial Buffer Size

Number

The amount of instances that is initially be allowed to be kept in memory to consume the stream and provide random access to it. If the stream contains more data than can fit into this buffer, then the buffer expands according to the Buffer size increment attribute, with an upper limit of maxInMemorySize. Default value is 100 instances.

100

Buffer Size Increment

Number

This is by how much the buffer size expands if it exceeds its initial size. Setting a value of zero or lower means that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised when the buffer gets full. Default value is 100 instances.

100

Max Buffer Size

Number

The maximum amount of memory to use. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error is raised. A value lower than, or equal to, zero means no limit.

Repeatable File Store Iterable

Field Type Description Default Value Required

In Memory Objects

Number

The maximum amount of instances that will be kept in memory. If more than that is required, then it will start to buffer the content on disk.

Buffer Unit

Enumeration, one of:

  • BYTE

  • KB

  • MB

  • GB

The unit in which maxInMemorySize is expressed

We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. You can read more and make your cookie choices here. By continuing to use this site you are giving us your consent to do this.