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

<file:copy>

Copies the file at the sourcePath into the targetPath.

If targetPath doesn't exists, 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 an IllegalArgumentException will be thrown.

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, IllegalArgumentException 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.

<file:create-directory>

Creates a new directory on directoryPath

<file:delete>

Deletes the file pointed by path, provided that it's not locked

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

If recursive is set to true but a found directory is rejected by the matcher, then there won't be any recursion into such directory.

<file:move>

Moves the file at the sourcePath into the targetPath.

If targetPath doesn't exists, 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 false, then an IllegalArgumentException will be thrown.

If the target file already exists, then it will be overwritten if the overwrite argument is true. Otherwise, IllegalArgumentException 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.

<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. A MimetypesFileTypeMap 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.

<file:rename>

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

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

<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 IllegalArgumentException 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. not set, then it defaults to FileConnectorConfig#getDefaultWriteEncoding()

<file:directory-listener>

Listens for near real-time events that happens on files contained inside a directory or on the directory itself. The events are not acquired by polling the filesystem but rather actually listening for operating system events.

Whenever a file (or the directory) is created, updated or deleted, this Source will fire a Message which payload reference the affected file and the attributes will be a ListenerFileAttributes instance.

There're however some special cases to be considered:

• If the file has been deleted, then it's not possible to obtain its content so the message payload will be null
• Also in the case of file deletion, all its attributes are also not available. Thus, the message attributes will actually be an instance of DeletedFileAttributes which throws IllegalStateException whenever a non available attribute is requested
• When the event references a directory, then the payload is also a null

When to use it

This source is useful in cases in which a flow should respond to changes done on the filesystem, examples being trigger files, transaction files being added on a drop folder, settings files updated, etc. All of the above cases could be done using a operation inside a poll scope (maybe also combined with a .

However, although polling is a powerful and reliable solution, it's not an efficient one. Because this listener relies on operating system notifications, it's much more efficient in terms of resources.

Reliability

The trade-off between a poll reliability and this listener's performance is reliability. Because operating system events don't generally include the concept of transaction or replay, there's no way to guarantee that no event is going to be lost in case of failure or server crash. Although you can always use mule to implement a reliable acquisition pattern, there's no fallback is such acquisition fails. What this means is that this listener is no silver bullet and it should not been seen as the recommended approach over a poll+list+watermark approach. Users should analyse each use case and environment to determine which the best option is.

Operating system limitations

This component's behaviour might be slightly different depending on the OS on which it is deployed. The main differences are usually (but not exclusively) related to:

• Overflows: In highly concurrent scenarios a given file might be associated to hundreds of events per second. Some OS might not be able to handle that gracefully and decide to drop some of those events or even fail.
• Polling: Some operation systems (like older versions of OSX) don't actually support file system notifications. In those cases, the JRE decides to compensate by using a high frequency poll, in which case the listener becomes pretty much the same as using a poll element