Nav

File Connector Documentation Reference

File connector used to manipulate file systems mounted on the host operation system.

This class serves as both extension definition and configuration. Operations are based on the standard BaseFileSystemOperations

Configurations


Config

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 that can be provided to this configuration.

x 

Default write encoding (DEPRECATED)

String

This parameter is deprecated and is ignored.

 

Time Between Size Check

Number

Wait time between size checks to determine if a file is ready to be read. This allows a file write to complete before processing. If no value is provided, the check is not performed. 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 attribute works in tandem with #timeBetweenSizeCheckUnit.

 

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

A TimeUnit which qualifies the #timeBetweenSizeCheck 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 will expire the instance at the exact moment that it becomes eligible. The runtime will actually purge the instances when it sees it fit.

 

Connection Types

Local FileSystem Connection

A ConnectionProvider which provides instances of FileSystem from instances of FileConnector

Parameters
Name Type Description Default Value Required

Working Directory

String

The directory to be considered as the root of every relative path used with this connector. If not provided, it will default to the value of the user.home system property. If that system property is not set, then the connector will fail to initialise.

 

Reconnection

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

 

Associated Operations

Associated Sources

Operations

Copy

<file:copy>

Copies the file at the sourcePath into the targetPath.

If targetPath doesn't exist, and neither does its parent, then an attempt will be made to create depending on the value of the createParentFolder argument. If such argument is , then a FILE:ILLEGAL_PATH will be thrown.

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, FILE:FILE_ALREADY_EXISTS error will be thrown.

As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it will be copied recursively.

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 which don't exists.

true

 

Overwrite

Boolean

whether or not overwrite the file if the target destination already exists.

false

 

Rename To

String

copied file's new name. If not provided, original file name will be kept.

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

For Configurations.

Throws

  • FILE:CONNECTIVITY  

  • FILE:ILLEGAL_PATH  

  • FILE:FILE_ALREADY_EXISTS  

  • FILE:RETRY_EXHAUSTED  

Create Directory

<file:create-directory>

Creates a new directory on directoryPath

Parameters

Name Type Description Default Value Required

Configuration

String

The name of the configuration to use.

x 

Directory Path

String

the new directory's name

x 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

For Configurations.

Throws

  • FILE:CONNECTIVITY  

  • FILE:ILLEGAL_PATH  

  • FILE:FILE_ALREADY_EXISTS  

  • FILE:RETRY_EXHAUSTED  

  • FILE:ACCESS_DENIED  

Delete

<file:delete>

Deletes the file pointed by path, provided that it's not 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 be deleted

x 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

For Configurations.

Throws

  • FILE:CONNECTIVITY  

  • FILE:ILLEGAL_PATH  

  • FILE:RETRY_EXHAUSTED  

  • FILE:ACCESS_DENIED  

List

<file:list>

Lists all the files in the directoryPath which 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 be listed

x 

Recursive

Boolean

whether to include the contents of sub-directories. Defaults to false.

false

 

File Matching Rules

a matcher used to filter the output list

 

Time Between Size Check

Number

wait time between size checks to determine if a file is ready to be read.

 

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

time unit to be used in the wait time between size checks.

 

Streaming Strategy

Configure if repeatable streams should be used and their behavior

 

Target Variable

String

The name of a variable on which the operation's output will be placed

 

Target Value

String

An expression that will be evaluated against the operation's output and the outcome of that expression will be stored in the target variable

#[payload]

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

Output

Type

Array of Message of [CursorProvider] payload and [Local File Attributes] attributes

For Configurations.

Throws

  • FILE:ILLEGAL_PATH  

  • FILE:ACCESS_DENIED  

Move

<file:move>

Moves the file at the sourcePath into the targetPath.

If targetPath doesn't exist, and neither does its parent, then an attempt will be made to create depending on the value of the createParentFolder argument. If such argument is , then a FILE:ILLEGAL_PATH will be thrown.

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, FILE:FILE_ALREADY_EXISTS error will be thrown.

As for the sourcePath, it can either be a file or a directory. If it points to a directory, then it will be moved recursively.

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 which don't exists.

true

 

Overwrite

Boolean

whether or not overwrite the file if the target destination already exists.

false

 

Rename To

String

moved file's new name. If not provided, original file name will be kept.

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

For Configurations.

Throws

  • FILE:CONNECTIVITY  

  • FILE:ILLEGAL_PATH  

  • FILE:FILE_ALREADY_EXISTS  

  • FILE:RETRY_EXHAUSTED  

Read

<file:read>

Obtains the content and metadata of a file at a given path. The operation itself returns a Message which payload is a InputStream with the file's content, and the metadata is represent as a LocalFileAttributes object that's placed as the message Message#getAttributes() attributes.

If the lock parameter is set to true, then a file system level lock will be 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 blindly relying on this lock.

This method also makes a best effort to determine the mime type of the file being read. The file's extension will be used to make an educated guess on the file's mime type. The user also has the chance to force the output encoding and mimeType through the outputEncoding and outputMimeType optional parameters.

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. Defaults to false.

false

 

Time Between Size Check

Number

wait time between size checks to determine if a file is ready to be read.

 

Time Between Size Check Unit

Enumeration, one of:

  • NANOSECONDS

  • MICROSECONDS

  • MILLISECONDS

  • SECONDS

  • MINUTES

  • HOURS

  • DAYS

time unit to be used in the wait time between size checks.

 

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 if repeatable streams should be used and their behavior

 

Target Variable

String

The name of a variable on which the operation's output will be placed

 

Target Value

String

An expression that will be evaluated against the operation's output and the outcome of that expression will be stored in the target variable

#[payload]

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

Output

Type

Binary

Attributes Type

For Configurations.

Throws

  • FILE:CONNECTIVITY  

  • FILE:FILE_LOCK  

  • FILE:ILLEGAL_PATH  

  • FILE:RETRY_EXHAUSTED  

  • FILE:ACCESS_DENIED  

Rename

<file:rename>

Renames the file pointed by path to the name provided on the to parameter

to argument should not contain any path separator. FILE:ILLEGAL_PATH will be thrown if this precondition is not honored.

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 overwrite the file if the target destination already exists.

false

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

For Configurations.

Throws

  • FILE:CONNECTIVITY  

  • FILE:ILLEGAL_PATH  

  • FILE:FILE_ALREADY_EXISTS  

  • FILE:RETRY_EXHAUSTED  

  • FILE:ACCESS_DENIED  

Write

<file:write>

Writes the content into the file pointed by path.

If the directory on which the file is attempting to be written doesn't exist, then the operation will either throw FILE:ILLEGAL_PATH error or create such folder depending on the value of the createParentDirectory.

If the file itself already exists, then the behavior depends on the supplied mode.

This operation also supports locking support depending on the value of the lock argument, but following 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

x 

Content

Binary

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

#[payload]

 

Encoding (DEPRECATED)

String

this parameter is deprecated and will do nothing if configured

 

Create Parent Directories

Boolean

whether or not to attempt creating any parent directories which don't exists.

true

 

Lock

Boolean

whether or not to lock the file. Defaults to false

false

 

Write Mode

Enumeration, one of:

  • OVERWRITE

  • APPEND

  • CREATE_NEW

a FileWriteMode. Defaults to OVERWRITE

OVERWRITE

 

Reconnection Strategy

A retry strategy in case of connectivity errors

 

For Configurations.

Throws

  • FILE:ILLEGAL_CONTENT  

  • FILE:CONNECTIVITY  

  • FILE:ILLEGAL_PATH  

  • FILE:FILE_ALREADY_EXISTS  

  • FILE:RETRY_EXHAUSTED  

  • FILE:ACCESS_DENIED  

Sources

On New or Updated File

<file:listener>

Polls a directory looking for files that have been created or updated. One message will be generated for each file that is found.

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

  • Set the autoDelete parameter to true: This will delete each processed file after it has been processed, causing all files obtained in the next poll to be necessarily new
  • Set moveToDirectory parameter: This will move each processed file to a different directory after it has been processed, achieving the same effect as autoDelete but without loosing the file
  • Use the watermarkMode parameter to only pick files that have been created/updated after the last poll was executed.

A matcher can also be used 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 on which polled files are contained

 

Recursive

Boolean

Whether or not to also files contained in sub directories.

true

 

Matcher

A matcher used to filter events on files which do not meet the matcher's criteria

 

Watermark Mode

Enumeration, one of:

  • DISABLED

  • MODIFIED_TIMESTAMP

  • CREATED_TIMESTAMP

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

DISABLED

 

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 TimeUnit which qualifies the #timeBetweenSizeCheck 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 only be executed on the primary node when running in Cluster

 

Scheduling Strategy

scheduling-strategy

Configures the scheduler that triggers the polling

x 

Streaming Strategy

Configure if repeatable streams should be used and their behavior

 

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 each file should be deleted after processing or not

false

 

Move To Directory

String

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

 

Rename To

String

This parameter works in tandem with moveToDirectory. Use this parameter to enter the name under which the file should be moved. Do not set this parameter if moveToDirectory 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 nor 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 will fail 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 ms) to reconnect

Count

Number

How many reconnection attempts to make

Reconnect Forever

Field Type Description Default Value Required

Frequency

Number

How often (in ms) to reconnect

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

Local File Attributes

Field Type Description Default Value Required

Last Modified Time

DateTime

x

Last Access Time

DateTime

x

Creation Time

DateTime

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

Created Since

DateTime

Files created before this date are rejected.

Created Until

DateTime

Files created after this date are rejected

Updated Since

DateTime

Files modified before this date are rejected

Updated Until

DateTime

Files modified after this date are rejected

Accessed Since

DateTime

Files which were last accessed before this date are rejected

Accessed Until

DateTime

Files which were last accessed after this date are rejected

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

This is the amount of memory that will be allocated in order to consume the stream and provide random access to it. If the stream contains more data than fits into this buffer, then the buffer expands according to the bufferSizeIncrement 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 will mean that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error will be raised when the buffer gets full.

Max Buffer Size

Number

This is the maximum amount of memory that will be used. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error will be raised. A value lower 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

Max 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 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.

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 useSecureHash is false.

Object Store

ObjectStore

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

This is the amount of instances that will be initially be allowed to be kept in memory in order to consume the stream and provide random access to it. If the stream contains more data than fits into this buffer, then the buffer expands according to the bufferSizeIncrement attribute, with an upper limit of maxInMemorySize. Default value is 100 instances.

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 will mean that the buffer should not expand, meaning that a STREAM_MAXIMUM_SIZE_EXCEEDED error will be raised when the buffer gets full. Default value is 100 instances.

Max Buffer Size

Number

This is the maximum amount of memory that will be used. If more than that is used then a STREAM_MAXIMUM_SIZE_EXCEEDED error will be raised. A value lower or equal to zero means no limit.

Repeatable File Store Iterable

Field Type Description Default Value Required

Max In Memory Size

Number

This is 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

Time Between Size Check Parameter Behavior

This wait will be performed at the moment of retrieving the content of the file. If the flow never accesses the content of the file, the check will not be done. Also, because this wait can take place in multiple message processors, this connector has no control over which thread will be the one performing the wait, thus leaving the possibility open to block threads not meant for this type of behavior.

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.

+