File Connector Reference | MuleSoft Documentation
# File Connector Reference
File Connector v1.5
Anypoint Connector for File (File Connector) manipulates file systems mounted on a host operation system.
This class serves as both extension definition and configuration. Operations are based on the standard `BaseFileSystemOperations`.
Release Notes: File Connector Release Notes
## Configurations
### Default Configuration
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
The name for this configuration. Connectors reference the configuration with this name.  
Connection |  Local FileSystem Connection | The connection types that can be provided to this configuration.  
Default write encoding (DEPRECATED) | This parameter is deprecated and is ignored.  
Time Between Size Check | Wait time between size checks to determine if a file is ready to 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 **Time between size check unit**.  
Time Between Size Check Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| A **Time unit** that qualifies the **Time between size check** attribute. | `MILLISECONDS`  
Expiration Policy |  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 Connection Provider that provides instances of File System from instances of File Connector.
###### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Working Directory | The directory to consider the root of every relative path used with this connector. If not provided, it defaults to the value of the `user.home` system property. If that system property is not set, then the connector fails to initialize.  
Reconnection |  | When an application deploys, 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.  
## Operations
  * Create Directory


## Associated Sources
  * On New or Updated File


### Copy
`<file: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 a `FILE:ILLEGAL_PATH` error is thrown.
If **Overwrite** is set to `true` and the target file already exists, then the target file is overwritten. Otherwise, a `FILE:FILE_ALREADY_EXISTS` error is thrown.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | The name of the configuration to use.  
Source Path | The path to the file to be copied.  
Target Path | The target directory where to copy the file.  
Create Parent Directories | Whether or not to create parent directories if they don’t exist.  
Overwrite | Whether or not to overwrite the file if the target destination already exists.  
Rename To | The new name for the copied file. If not provided, original file name is kept.  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### Throws
  * FILE:CONNECTIVITY
  * FILE:ILLEGAL_PATH
  * FILE:FILE_ALREADY_EXISTS
  * FILE:RETRY_EXHAUSTED


### Create Directory
`<file:create-directory>`
Creates a new directory on **Directory path**.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | The name of the configuration to use.  
Directory Path | The new directory’s name.  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### Throws
  * FILE:CONNECTIVITY
  * FILE:ILLEGAL_PATH
  * FILE:FILE_ALREADY_EXISTS
  * FILE:RETRY_EXHAUSTED
  * FILE:ACCESS_DENIED


### Delete
`<file:delete>`
Deletes the file that the path field points to, provided that the file is not locked.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | The name of the configuration to use.  
The path to the file to be deleted.  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### Throws
  * FILE:CONNECTIVITY
  * FILE:ILLEGAL_PATH
  * FILE:RETRY_EXHAUSTED
  * FILE:ACCESS_DENIED


### List
`<file:list>`
Lists all the files in the **Directory path** that match a matcher.
If the listing encounters a directory, the output list includes its contents depending on the value of the **Recursive** parameter.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | The name of the configuration to use.  
Directory Path | The path to the directory to be listed.  
Recursive | Whether to include the contents of subdirectories.  
File Matching Rules | A matcher used to filter the output list.  
Time Between Size Check | Wait time between size checks to determine if a file is ready to read.  
Time Between Size Check Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| Time unit to be used in the wait time between size checks.  
Local Subset List | Limit and sort the number of files returned.  
Streaming Strategy | 
  * Repeatable In Memory Iterable
  * Repeatable File Store Iterable
  * non-repeatable-iterable

| Configure if repeatable streams should be used and their behavior.  
Target Variable | The name of a variable on which the operation’s output is placed.  
Target Value | An expression to evaluate against the operation’s output and the outcome of that expression is stored in the target variable. | `#[payload]`  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### Output
Array of Message of [CursorProvider] payload and [Local File Attributes] attributes  
---  
#### For Configurations
  * Default Configuration


#### Throws
  * FILE:ILLEGAL_PATH
  * FILE:ACCESS_DENIED


### Move
`<file: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 a `FILE: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`, a `FILE:FILE_ALREADY_EXISTS` error will be thrown.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration | The name of the configuration to use.  
Source Path | The path to the file to be copied.  
Target Path | The target directory.  
Create Parent Directories | Whether or not to attempt creating any parent directories which don’t exists.  
Overwrite | Whether or not overwrite the file if the target destination already exists.  
Rename To | Moved file’s new name. If not provided, original file name is kept.  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### Throws
  * FILE:CONNECTIVITY
  * FILE:ILLEGAL_PATH
  * FILE:FILE_ALREADY_EXISTS
  * FILE:RETRY_EXHAUSTED
| A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### 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 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 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 is 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 | The name of the configuration to use.  
File Path | The path to the file to be read  
Whether or not to lock the file. Defaults to false.  
Time Between Size Check | 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

| time unit to be used in the wait time between size checks.  
Output Mime Type | The MIME type of the payload that this operation outputs.  
Encoding | The encoding of the payload that this operation outputs.  
Streaming Strategy | 
  * Repeatable In Memory Stream
  * Repeatable File Store Stream
  * non-repeatable-stream

| Configure if repeatable streams should be used and their behavior  
Target Variable | The name of a variable on which the operation’s output will be placed  
Target Value | An expression to evaluate against the operation’s output and the outcome of that expression will be stored in the target variable | #[payload]  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### Output
**Attributes Type** |  Local File Attributes  
---|---  
#### For Configurations
  * Default Configuration


#### Throws
  * FILE:CONNECTIVITY
  * FILE:FILE_LOCK
  * FILE:ILLEGAL_PATH
  * FILE:RETRY_EXHAUSTED
  * FILE:ACCESS_DENIED


### Rename
`<file:rename>`
Renames the file pointed by the path to the name provided on the `to` parameter. The `to` argument should not contain any path separator. FILE:ILLEGAL_PATH is thrown if this precondition is not honored.
#### Parameters
Name | Type | Description | Default Value | Required  
---|---|---|---|---  
Configuration |  The name of the configuration to use.  
The path to the file to be renamed.  
The file’s new name.  
Whether or not overwrite the file if the target destination already exists.  
Reconnection Strategy | 
  *   * Reconnect Forever

|  A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### 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 | The name of the configuration to use.  
The path of the file to be written  
The content to be written into the file. Defaults to the current Message payload | #[payload]  
Encoding (DEPRECATED) | This parameter is deprecated and does nothing if configured.  
Create Parent Directories | Whether or not to attempt creating any parent directories which don’t exists.  
Whether or not to lock the file. Defaults to false  
Write Mode |  Enumeration, one of:
  * OVERWRITE
  * APPEND
  * CREATE_NEW

| a FileWriteMode. Defaults to OVERWRITE | OVERWRITE  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors.  
#### For Configurations
  * Default Configuration


#### 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 is generated for each file that is found.
The key part of this functionality is how to determine that a file is actually new.
These are the strategies for that:
  * Set the `autoDelete` parameter to `true`: This deletes each processed file after it has been processed, causing all files obtained in the next poll to be necessarily new.
  * Set `moveToDirectory` parameter: This moves each processed file to a different directory after it has been processed, achieving the same effect as `autoDelete<` but without losing the file.
  * Use the watermarkMode parameter to pick only files that are created or 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 | The name of the configuration to use.  
Directory | The directory on which polled files are contained.  
Recursive | Whether or not to also files contained in sub directories.  
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 | 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

| A **Time unit** that qualifies the **Time between size check**.  
Output Mime Type | The MIME type of the payload that this operation outputs.  
Encoding | The encoding of the payload that this operation outputs.  
Primary Node Only | 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.  
Streaming Strategy | 
  * Repeatable In Memory Stream
  * Repeatable File Store Stream
  * non-repeatable-stream

| Configure if repeatable streams should be used and their behavior.  
Redelivery Policy |  Redelivery Policy | Defines a policy for processing the redelivery of the same message  
Reconnection Strategy | 
  *   * Reconnect Forever

| A retry strategy in case of connectivity errors  
Auto Delete | Whether each file should be deleted after processing or not.  
Move To Directory | If provided, each processed file will be moved to a directory pointed by this path.  
Rename To | 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 moveToDirectory hasn’t been set as well.  
Apply Post Action When Failed | Whether any of the post actions (**Auto delete** and **Move to directory**) should also be applied in case the file failed to be processed. If set to `false`, no failed files are moved nor deleted.  
Overwrite | Enables you to overwrite the target file when the destination file has the same name.  
#### Output
**Attributes Type** |  Local File Attributes  
---|---  
#### For Configurations
  * Default Configuration


## Types
### Reconnection
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Fails Deployment | 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 | 
  *   * Reconnect Forever
| A retry strategy in case of connectivity errors  
Auto Delete | Whether each file should be deleted after processing or not.  
Move To Directory | If provided, each processed file will be moved to a directory pointed by this path.  
Rename To | 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 moveToDirectory hasn’t been set as well.  
Apply Post Action When Failed | Whether any of the post actions (**Auto delete** and **Move to directory**) should also be applied in case the file failed to be processed. If set to `false`, no failed files are moved nor deleted.  
Overwrite | Enables you to overwrite the target file when the destination file has the same name.  
#### Output
**Attributes Type** |  Local File Attributes  
---|---  
#### For Configurations
  * Default Configuration


## Types
### Reconnection
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Fails Deployment | 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 | 
  *   * Reconnect Forever

| The reconnection strategy to use  
### Reconnect
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often in milliseconds to reconnect.  
How many reconnection attempts to make.  
blocking | If false, the reconnection strategy runs in a separate, non-blocking thread.  
### Reconnect Forever
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Frequency | How often in milliseconds to reconnect.  
blocking | If false, the reconnection strategy runs in a separate, non-blocking thread.  
### Expiration Policy
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Max Idle Time | 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

| A time unit that qualifies the **Max idle time** attribute.  
### Local File Attributes
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Last Modified Time  
Last Access Time  
Creation Time  
Regular File  
Directory  
Symbolic Link  
### Matcher
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Created Since | Files created before this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead.  
Created Until | Files created after this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead.  
Updated Since | Files modified before this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead.  
Updated Until | Files modified after this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead.  
Accessed Since | Files that were last accessed before this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead.  
Accessed Until | Files that were last accessed after this date are rejected. Any timezone specification in this value is ignored and the Mule server’s time zone is used instead.  
Not Updated In The Last | Minimum time that should pass since a file was last updated for it not to be rejected. This attribute works in tandem with **Time unit**.  
Updated In The Last | Maximum time that should pass since a file was last updated for it not to be rejected. This attribute works in tandem with **Time unit**.  
Time Unit |  Enumeration, one of:
  * NANOSECONDS
  * MICROSECONDS
  * MILLISECONDS
  * SECONDS
  * MINUTES
  * HOURS

| A **Time unit** that qualifies the **Updated in the last** and the **Not updated in the last** attributes. | MILLISECONDS  
Filename Pattern  
Path Pattern  
Directories |  Enumeration, one of:
  * REQUIRE
  * INCLUDE
  * EXCLUDE

| Controls whether directories are included in the results.  
Regular Files |  Enumeration, one of:
  * REQUIRE
  * INCLUDE
  * EXCLUDE

  
Sym Links |  Enumeration, one of:
  * REQUIRE
  * INCLUDE
  * EXCLUDE
| A **Time unit** that qualifies the **Updated in the last** and the **Not updated in the last** attributes. | MILLISECONDS  
Filename Pattern  
Path Pattern  
Directories |  Enumeration, one of:
  * REQUIRE
  * INCLUDE
  * EXCLUDE

| Controls whether directories are included in the results.  
Regular Files |  Enumeration, one of:
  * REQUIRE
  * INCLUDE
  * EXCLUDE

  
Sym Links |  Enumeration, one of:
  * REQUIRE
  * INCLUDE
  * EXCLUDE

  
### Repeatable In Memory Stream
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Initial Buffer Size | 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 **Buffer size increment** attribute, with an upper limit of the **Max in memory size**.  
Buffer Size Increment | How much to expand the buffer size 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 is thrown when the buffer gets full.  
Max in Memory Size | This is the maximum amount of memory to use. If more than the specified maximum is used, then a `STREAM_MAXIMUM_SIZE_EXCEEDED` error is thrown. A value lower than, or equal to, zero means no limit.  
Buffer Unit |  Enumeration, one of: | The unit in which all these attributes are expressed  
### Repeatable File Store Stream
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Max In Memory Size | 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: | The unit in which **Max in memory size** is expressed  
In Memory Objects | Defines the maximum memory the stream uses to keep data in memory. If more than the specified memory is consumed, then the system starts to buffer the content on disk.  
### Redelivery Policy
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Max Redelivery Count | The maximum number of times a message can be redelivered and processed unsuccessfully before triggering `process-failed-message`.  
Use Secure Hash | Whether to use a secure hash algorithm to identify a redelivered message.  
Message Digest Algorithm | The secure hashing algorithm to use. If not set, the default is `SHA-256`.  
Id Expression | Defines one or more expressions to use to determine when a message has been redelivered. You can set this property only if **Use secure hash** is not selected.  
Object Store |  ObjectStore | The object store where the redelivery counter for each message is stored.  
### Local Subset List
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Criteria |  Enumeration, one of: **ALPHABETICALLY** DATE_MODIFIED **DATE_CREATED** SIZE ** PATH | DATE_MODIFIED  
Enumeration, one of: **ASCENDING** DESCENDING | DESCENDING  
### Repeatable In Memory Iterable
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Initial Buffer Size | 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 **Buffer size increment** attribute, with an upper limit of **Max in memory instances**. Default value is 100 instances.  
Buffer Size Increment | 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 in Memory instances | This is the maximum number of memory instances to use. If more than the specified maximum is used, then a `STREAM_MAXIMUM_SIZE_EXCEEDED` error is thrown. A value lower than, or equal to, zero means no limit.  
### Repeatable File Store Iterable
Field | Type | Description | Default Value | Required  
---|---|---|---|---  
Max In Memory Size | 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: | The unit in which maxInMemorySize is expressed  
### Time Between Size Check Parameter Behavior
The Write operation on a file can take time to complete and get the file ready to read or access. Use the `timeBetweenSizeCheck` parameter to prevent an operation from accessing an incomplete file. When you set this parameter, it verifies the file’s size before accessing the file contents. The verification validates that the file’s size does not vary after waiting for the amount of time specified by the parameters `timeBetweenSizeCheck` and `timeBetweenSizeCheckUnit`. The `timeBetweenSizeCheck` parameter then indicates the time to wait between each verification, which is performed twice. If the file’s size remains the same during both times, this assumes that the Write operation is complete and the access operation can continue, otherwise an exception is thrown. The performed wait indicates that the thread executing the operation goes to sleep for the indicated period of time. This wait occurs at the moment of retrieving the content of the file. If the flow never accesses the content of the file, the check is not performed.
In Mule runtime engine version 4.1 and 4.2, this wait can take place in multiple message processors, and the File Connector has no control over which thread is the one performing the wait. Any thread from any thread pool, even a CPU-intensive thread, which is not meant for this kind of task, can be the one performing the wait.   
---  
## See Also
MuleSoft Help Center