Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.6)
  3. Reference
  4. Transports Reference

  5. File Transport Reference

File Transport Reference

Mule Runtime Engine versions 3.5, 3.6, and 3.7 reached End of Life on or before January 25, 2020. For more information, contact your Customer Success Manager to determine how you can migrate to the latest Mule version.

The File transport allows files on the local file system to be read from and written to. The connector can be configured to filter the file it reads and the way files are written, such as whether Mule places the output in a new file or appends the output to an existing file.

Note: In code examples in this guide, spring-beans-current.xsd is a placeholder. To locate the correct version, see http://www.springframework.org/schema/beans/.

Transport Info

Feature Value Description

Transport

File

The name/protocol of the transport

Doc

JavaDoc, SchemaDoc

Javadoc and Schema doc

Inbound

check

Whether the transport can receive inbound events and can be used for an inbound endpoint.

Outbound

check

Whether the transport can produce outbound events and be used with an outbound endpoint.

Request

check

Whether this endpoint can be queried directly with a request call (via MuleClient or the EventContext).

Transactions

error

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

check

Whether this transport can process messages that come in on an input stream. This allows for very efficient processing of large data.

Retries

error

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

one-way

Message Exchange Patterns supported by this transport.

Default MEP

one-way

The default MEP for endpoints that use this transport that do not explicitly configure a MEP

Maven Artifact

org.mule.transport:transportmule-transport-file

The group name and artifact name for this transport in Maven

Namespace and Syntax

XML Namespace

xmlns:file="http://www.mulesoft.org/schema/mule/file"

XML Schema Location

http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.6/mule-file.xsd

Connector Syntax

<!-- Typical Connector for Inbound Endpoint: Read files -->
<file:connector name="input" fileAge="500" autoDelete="true" pollingFrequency="100" moveToDirectory="/backup" moveToPattern="#[message.inboundProperties['originalFilename']].backup"/>

<!-- Typical Connector for Outbound Endpoint: Write files -->
<file:connector name="output" outputAppend="true" outputPattern="#[server.dateTime]-#[message.inboundProperties['originalFilename']]" />

Endpoint Syntax

You can express file endpoints using standard File URI syntax:

file://<path>[MULE:?params]

For example, to connect to a directory called /temp/files:

Unix

file:///temp/files

Note: The extra slash denotes a path from the root (absolute path).

Windows

file:///C:/temp/files

The Unix style still works in Windows if you map to a single drive (the one Mule was started from).

To specify a relative path use:

file://./temp

Or:

file://temp

Note: Only two slashes are used for the protocol, so it’s a relative path.

In Unix, relative paths are relative to the root directory ( / ). For example, specifying file://temp indicates directory /temp. In Windows, relative paths are relative to the drive where Mule resides, for example C:\.
To specify a Windows relative path, use the backslash \, for example \temp specifies C:\temp if Mule resides in drive C:\.

Or:

file://?address=./temp

To connect to a Windows network drive:

file:192.168.0.1/temp/

Inbound Endpoint

<file:inbound-endpoint connector-ref="input" path="/tmp/input"/>

Outbound Endpoint

<file:outbound-endpoint connector-ref="output" path="/tmp/output"/>

Considerations

Mule ESB provides lots of functionality ready to use that can just be modified by changing a XML file. Everyone knows how to handle files in their programming language, but when advanced features are required, coding gets complex. Mule ESB easily allows you to rename and archive files and handles the uncomfortable task of validating when input files are completely generated.

  • This transport should be used to both read and write files in the filesystem. Use the inbound endpoint to read files every certain period of time, filtering input files by different name patterns and deleting, moving or leaving the file as it is once processed. The outbound endpoint allows you to generate new files (the file name can be defined in runtime) or to append content to an existing file.

  • Take into account that the account running mule (in standalone mode, the user that launched the Mule ESB server, if not, the user which runs the Application Server) should have read and/or write permissions on the directories configured for this transport.

  • Be careful not to permanently delete or overwrite input/output files. Be careful when using, for example, autoDelete and moveToDirectory attributes.

  • Check the examples below and find out how to copy files from one directory to another, process input files while saving a backup of the input file and creating a new file with a specific name.

  • Though most configuration parameters can be defined globally at in the connector, they can be overridden in the endpoint configuration.

  • If streaming is enabled a ReceiverFileInputStream is used as the payload for each file that is processed. This input stream’s close() method takes care of moving the file or deleting it. Streams are closed by transformers reading the input stream. If you process the stream in your own component implementation make sure to properly close the stream after reading.

  • When configured to use a working directory, Mule add two properties to the message to indicate the source from which the file was read:

    • sourceFileName: contains the same value as the originalFilename property which Mule uses when no workDirectory is configured

    • sourceDirectory: contains the same value as the originalDirectory property which Mule uses when no workDirectory is configured.

Features

  • Read files at a regular polling interval

  • Write files

Usage

To use the file transport in your Mule configuration, Schema and use the <file:`connector>`, <file:`inbound-endpoint>` and/or <file:`outbound-endpoint>` elements. Refer to the Example Configurations below.

You can use the following expressions inside attributes:

  • #[function:dateStamp]

  • #[function:datestamp:dd-MM-yy]

  • #[function:systime]

  • #[function:uuid]

  • #[message.inboundProperties.originalFilename]

  • #[function:count]

  • #[message.inboundProperties['messagepropertyname']

For new dateTime functions introduced into MEL with Mule 3.4 and later, see MEL Date and Time Functions.

Example Configurations

The following simple example copies files from /tmp/input ❸ to /tmp/output ❹ every 1 second (1000 ms) ❷. As input files are not deleted ❶ they are processed every time. Changing autoDelete to true just moves files.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:file="http://www.mulesoft.org/schema/mule/file"
      xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
         http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.6/mule.xsd
         http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.6/mule-file.xsd">

  <file:connector name="input" autoDelete="false" ❶ pollingFrequency="1000" ❷ />

  <file:connector name="output" outputAppend="false"/>

  <flow name="copyFile">
    <file:inbound-endpoint connector-ref="input" path="/tmp/input"/> ❸
    <file:outbound-endpoint connector-ref="output" path="/tmp/output"/> ❹
  </flow>
</mule>

Note : In these code examples, spring-beans-current.xsd is a placeholder. To locate the correct version, see http://www.springframework.org/schema/beans/ .

The following example moves files ❶ from /tmp/input to /tmp/output every 5 second (5000 ms) ❸, saving a backup file of the original file (with the extension backup) in /tmp/backup ❹. The new file is renamed with the current date and time as prefix ❺.

Note: fileAge prevents moving files that are still being generated as the file has to be untouched for at least half a second ❷.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:file="http://www.mulesoft.org/schema/mule/file"
      xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
         http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.6/mule.xsd
         http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.6/mule-file.xsd">

  <file:connector name="input" autoDelete="true" ❶ fileAge="500" ❷ pollingFrequency="5000" ❸ />

  <file:connector name="output" outputAppend="false"/>

  <flow name="moveFile">
    <file:inbound-endpoint connector-ref="input" path="/tmp/input"
                      moveToDirectory="/tmp/backup"
                      moveToPattern="#[message.inboundProperties['originalFilename']].backup"/>
    <file:outbound-endpoint connector-ref="output" path="/tmp/output"
                      outputPattern="#[function:datestamp]-#[message.inboundProperties['originalFilename']]"/>
  </flow>
</mule>

The following example shows different connector configurations. The third example overrides parts of the transport implementation ❷ and does not delete the file after processing it ❶. The inbound endpoint moves it to a directory for archiving after it is processed ❸.

<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:file="http://www.mulesoft.org/schema/mule/file"
      xsi:schemaLocation="
          http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/3.6/mule-file.xsd
          http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/3.6/mule.xsd">

  <file:connector name="sendConnector" outputAppend="true" outputPattern="[TARGET_FILE]" />

  <file:connector name="receiveConnector" fileAge="500" autoDelete="true" pollingFrequency="100" />

  <file:connector name="inboundFileConnector" pollingFrequency="10000"
              streaming="false" autoDelete="false"> ❶
    <service-overrides messageFactory="org.mule.transport.file.FileMuleMessageFactory"
      inboundTransformer="org.mule.transformer.NoActionTransformer" /> ❷
    <file:expression-filename-parser />
  </file:connector>

  <flow name="RefreshFileManager">
    <file:inbound-endpoint connector-ref="inboundFileConnector"
      path="C:/temp/filewatcher/inbox" moveToDirectory="C:/temp/filewatcher/history"
      moveToPattern="#[function:datestamp]-#[message.inboundProperties['originalFilename']]" /> ❸

    ...
  </flow>

  ...
</mule>

Configuration Options

File Transport inbound endpoint attributes:

Name Description Default

autoDelete

Set this attribute to false if you don’t want Mule to delete the file after processing the file

true

fileAge

Setting this value (minimum age in milliseconds for a file to be processed) is useful when consuming large files, as Mule waits before reading this file until the file last modification timestamp indicates that the file is older than this value

true

moveToDirectory

Use this parameter to have Mule save a backup copy of the file it reads. Note: If a file already exists in the directory, moveToDirectory moves the file to the directory only one time. Subsequent attempts to move the same file to the directory result in Mule throwing an exception.

moveToPattern

Use this parameter together with moveToPattern to rename a copy of the backed up file

pollingFrequency

Set the frequency in milliseconds for checking the read directory

0

recursive

Use this parameter so Mule recurses when a directory is read

false

streaming

If you want the payload to be a byte array instead of a FileInputStream, set this parameter to false

true

workDirectory†

If you require moving input files before they are processed by Mule, then assign a working directory (in the same file system) with this parameter

workFileNamePattern

Use this parameter together with workDirectory to rename input files before processing them

† When configured to use a working directory, Mule adds two properties to the message to indicate the source from which the file was read:

  • sourceFileName: Contains the same value as the originalFilename property which Mule uses when no workDirectory is configured

  • sourceDirectory: Contains the same value as the originalDirectory property which Mule uses when no workDirectory is configured.

File Transport outbound endpoint attributes

Name Description Default

outputAppend

If the file to be written already exists, set this parameter to true to append new contents instead of overwriting the file.

false

outputPattern

The pattern to use when writing a file to disk.

Connector

The File connector configures the default behavior for File endpoints that reference the connector. If there is only one File connector configured, all file endpoints use that connector.

Attributes of connector

Name Description

writeToDirectory

The directory path where the file should be written on dispatch. This path is usually set as the endpoint of the dispatch event, however this allows you to explicitly force a single directory for the connector.
Type: string
Required: no
Default: none

readFromDirectory

The directory path where the file should be read from. This path is usually set as the inbound endpoint, however this allows you to explicitly force a single directory for the connector.
Type: string
Required: no
Default: none

autoDelete

If set to true (the default), it causes the file to be deleted once it is read. If streaming is turned on, this occurs when the InputStream for the file is closed. Otherwise the file is read into memory and deleted immediately. To access the java.io.File object set this property to false and specify a NoActionTransformer transformer for the connector. Mule does not delete the file, so it is up to the component to delete it when it is done. If the moveToDirectory is set, the file is first moved, then the File object of the moved file is passed to the component. It is recommended that a moveToDirectory is specified when turning autoDelete off.
Type: boolean
Required: no
Default: true

outputAppend

Whether the output should be appended to the existing file.
Type: boolean
Required: no
Default: false

serialiseObjects

Determines whether objects should be serialized to the file. If false (the default), the raw bytes or text are written.
Type: boolean
Required: no
Default: none

streaming

Whether a FileInputStream should be sent as the message payload (if true) or a byte array. (if false).
Type: boolean
Required: no
Default: true

workDirectory

(As of Mule 2.1.4) The directory path where the file should be moved to prior to processing. The work directory must reside on the same file system as the read directory.
Type: string
Required: no
Default: none

workFileNamePattern

(As of Mule 2.1.4) The pattern to use when moving a file to a new location determined by the workDirectory property. You can use the patterns supported by the filename parser configured for this connector.
Type: string
Required: no
Default: none

recursive

Whether to recurse or not when a directory is read
Type: boolean
Required: no
Default: false

pollingFrequency

The frequency in milliseconds that the read directory should be checked (default is 0). Note that the read directory is specified by the endpoint of the listening component.
Type: long
Required: no
Default: none

fileAge

Minimum age (ms) for a file to be processed. This can be useful when consuming large files. It tells Mule to wait for a period of time before consuming the file, allowing the file to be completely written before the file is processed.
Type: long
Required: no
Default: none

moveToPattern

The pattern to use when moving a read file to a new location determined by the moveToDirectory property. This can use the patterns supported by the filename parser configured for this connector.
Type: string
Required: no
Default: none

moveToDirectory

The directory path where the file should be written after it has been read. If this is not set, the file is deleted after it has been read. Note: moveToDirectory moves a file only one time if the file already exists with the same name. Be careful not to permanently delete or overwrite input/output files.
Type: string
Required: no
Default: none

outputPattern

The pattern to use when writing a file to disk. This can use the patterns supported by the filename parser configured for this connector.
Type: string
Required: no
Default: none

Child Elements of connector

Name Cardinality Description

abstract-filenameParser

0..1

The abstract-filenameParser element is a placeholder for filename parser elements. The filename parser is set on the connector used when writing files to a directory. The parser converts the outputPattern attribute to a string using the parser and the current message. The default implementation used is expression-filename-parser, but you can also specify a custom-filename-parser.

Associated Elements

Endpoint

Attributes of endpoint

Name Description

path

A file directory location.
Type: string
Required: no
Default: none

pollingFrequency

The frequency in milliseconds that the read directory should be checked (default is 0). Note that the read directory is specified by the endpoint of the listening component.
Type: long
Required: no
Default: none

fileAge

Minimum age (ms) for a file to be processed. This can be useful when consuming large files. It tells Mule to wait for a period of time before consuming the file, allowing the file to be completely written before the file is processed.
Type: long
Required: no
Default: none

moveToPattern

The pattern to use when moving a read file to a new location determined by the moveToDirectory property. This can use the patterns supported by the filename parser configured for this connector.
Type: string
Required: no
Default: none

moveToDirectory

The directory path where the file should be written after it has been read. If this is not set, the file is deleted after it has been read. Note: If a file already exists in the directory, moveToDirectory moves the file to the directory only one time. Subsequent attempts to move the same file to the directory result in Mule throwing an exception.
Type: string
Required: no
Default: none

comparator

Sorts incoming files using the specified comparator, such as comparator="org.mule.transport.file.comparator.OlderFirstComparator". The class must implement the java.util.Comparator interface.
Type: class
ame, Required
no, Default: none

reverseOrder

Whether the comparator order should be reversed. Default is false.
Type: boolean
Required: no
Default: none

outputPattern

The pattern to use when writing a file to disk. This can use the patterns supported by the filename parser configured for this connector.
Type: string
Required: no
Default: none

No child elements for endpoint.

Inbound Endpoint

Attributes of inbound-endpoint

Name Description

path

A file directory location.
Type: string
Required: no
Default: none

pollingFrequency

The frequency in milliseconds that the read directory should be checked (default is 0). Note that the read directory is specified by the endpoint of the listening component.
Type: long
Required: no
Default: none

fileAge

Minimum age (ms) for a file to be processed. This can be useful when consuming large files. It tells Mule to wait for a period of time before consuming the file, allowing the file to be completely written before the file is processed.
Type: long
Required: no
Default: none

moveToPattern

The pattern to use when moving a read file to a new location determined by the moveToDirectory property. This can use the patterns supported by the filename parser configured for this connector.
Type: string
Required: no
Default: none

moveToDirectory

The directory path where the file should be written after it has been read. If this is not set, the file is deleted after it has been read. Note: If a file already exists in the directory, moveToDirectory moves the file to the directory only one time. Subsequent attempts to move the same file to the directory result in Mule throwing an exception.
Type: string
Required: no
Default: none

comparator

Sorts incoming files using the specified comparator, such as comparator="org.mule.transport.file.comparator.OlderFirstComparator". The class must implement the java.util.Comparator interface.
Type: class name
Required: no
Default: none

reverseOrder

Whether the comparator order should be reversed. Default is false.
Type: boolean
Required: no
Default: false

No child elements for inbound-endpoint.

Outbound Endpoint

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

path

string

no

A file directory location.

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.

No child elements of <outbound-endpoint…​>

File to Byte Array Transformer

The file-to-byte-array-transformer element configures a transformer that reads the contents of a java.io.File into a byte array (byte[]).

No child elements of <file-to-byte-array-transformer…​>

File to String Transformer

The file-to-string-transformer element configures a transformer that reads the contents of a java.io.File into a java.lang.String.

No child elements of <file-to-string-transformer…​>

Note: This transformer does not close file streams. This prevents files from being deleted or moved if the flow is asynchronous. If you have streaming enabled for an asynchronous endpoint, use the ObjectToString transformer instead.

Filename Wildcard Filter

The filename-wildcard-filter element configures a filter that can be used to restrict the files being processed by applying wildcard expressions to the filename. For example, you can read only .xml and .txt files by entering the following: <file:filename-wildcard-filter pattern=".txt,.xml"/>

No child elements of <filename-wildcard-filter…​>

Filename Regex Filter

The filename-regex-filter element configures a filter that can be used to restrict the files being processed by applying Java regular expressions to the filename, such as pattern="myCustomerFile(.*)".

No child elements of <filename-regex-filter…​>

Expression Filename Parser

The expression-filename-parser element configures the ExpressionFilenameParser, which can use any expression language supported by Mule to construct a file name for the current message. Expressions can be xpath, xquery, ognl, mvel, header, function, and more.

No attributes of <expression-filename-parser…​>

No child elements of <expression-filename-parser>.

For example, an XPath expression can be defined to pull a message ID out of an XML message and use that as the file name as follows:

#[xpath:/message/header/@id]

Following is an example of using the parser:

<file:connector name="FileConnector" >
  <file:expression-filename-parser/>
</file:connector>
...
<file:outbound-endpoint path="file://temp"
outputPattern="#[message.inboundProperties['originalFilename']]--#[function:datestamp].txt"/>

This parser supersedes <legacy-filename-parser> from previous releases of Mule. The following demonstrates how to achieve the same results when using <expression-filename-parser> over <legacy-filename-parser>.

  • #[DATE] : #[function:dateStamp]

  • #[DATE:dd-MM-yy] : #[function:datestamp:dd-MM-yy]

  • #[SYSTIME] : #[function:systime]

  • #[UUID] : #[function:uuid]

  • #[ORIGINALNAME] : #[message.inboundProperties.originalFilename]

  • #[COUNT] : #[function:count] - note that this is a global counter. If you want a local counter per file connector then you should use the legacy-filename-parser.

  • #[message property name] : #[message.inboundProperties['messagepropertyname']

Note: OGNL is deprecated in Mule 3.6 and will be removed in Mule 4.0.

Custom Filename Parser

The custom-filename-parser element allows the user to specify a custom filename parser. The implementation must implement org.mule.transport.file.FilenameParser.

Attributes of <custom-filename-parser…​>

Name Type Required Default Description

class

string

yes

The implementation class name that implements org.mule.transport.file.FilenameParser.

No child elements for <custom-filename-parser>.

Abstract filenameParser

The abstract-filenameParser element is a placeholder for filename parser elements. The filename parser is set on the connector used when writing files to a directory. The parser converts the outputPattern attribute to a string using the parser and the current message. The default implementation used is expression-filename-parser, but you can also specify a custom-filename-parser.

No attributes of <abstract-filenameParser>.

No child elements for <abstract-filenameParser>.

Schema

Access the schema file for the File Transport.

Javadoc API Reference

Javadoc for File Transport.

Maven

The File Transport can be included with the following dependency:

<dependency>
  <groupId>org.mule.transports</groupId>
  <artifactId>mule-transport-file</artifactId>
</dependency>

Extending this Module or Transport Best Practices

If reading input files which are generated directly in the input path, configure the fileAge attribute in the connector or endpoint. In this way, Mule processes these files after they are completely written to disk.