Spring Integration's File support extends the Spring Integration Core with a dedicated vocabulary to deal with reading, writing, and transforming files. It provides a namespace that enables elements defining Channel Adapters dedicated to files and support for Transformers that can read file contents into strings or byte arrays.

This section will explain the workings of FileReadingMessageSource and FileWritingMessageHandler and how to configure them as beans. Also the support for dealing with files through file specific implementations of Transformer will be discussed. Finally the file specific namespace will be explained.

A FileReadingMessageSource can be used to consume files from the filesystem. This is an implementation of MessageSource that creates messages from a file system directory.

<bean id="pollableFileSource"
      class="org.springframework.integration.file.FileReadingMessageSource"
        p:inputDirectory="file:${input.directory}"/>

To prevent creating messages for certain files, you may supply a FileListFilter. By default, an AcceptOnceFileListFilter is used. This filter ensures files are picked up only once from the directory.

<bean id="pollableFileSource"
      class="org.springframework.integration.file.FileReadingMessageSource"
        p:inputDirectory="file:${input.directory}"
        p:filter-ref="customFilterBean"/>

A common problem with reading files is that a file may be detected before it is ready. The default AcceptOnceFileListFilter does not prevent this. In most cases, this can be prevented if the file-writing process renames each file as soon as it is ready for reading. A pattern-matching filter that accepts only files that are ready (e.g. based on a known suffix), composed with the default AcceptOnceFileListFilter allows for this. The CompositeFileListFilter enables the composition.

<bean id="pollableFileSource"
      class="org.springframework.integration.file.FileReadingMessageSource"
        p:inputDirectory="file:${input.directory}"
        p:filter-ref="compositeFilter"/>
<bean id="compositeFilter" class="org.springframework.integration.file.filters.CompositeFileListFilter">
    <constructor-arg>
        <list>
            <bean class="org.springframework.integration.file.filters.AcceptOnceFileListFilter" />
            <bean class="org.springframework.integration.file.filters.PatternMatchingFileListFilter">
                <constructor-arg value="^test.*$"/>
            </bean>
        </list>
    </constructor-arg>
</bean>

The configuration can be simplified using the file specific namespace. To do this use the following template.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:integration="http://www.springframework.org/schema/integration"
  xmlns:file="http://www.springframework.org/schema/integration/file"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
      http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
      http://www.springframework.org/schema/integration
      http://www.springframework.org/schema/integration/spring-integration-2.0.xsd
      http://www.springframework.org/schema/integration/file
      http://www.springframework.org/schema/integration/file/spring-integration-file-2.0.xsd">
</beans>

Within this namespace you can reduce the FileReadingMessageSource and wrap it in an inbound Channel Adapter like this:

 <file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory}" prevent-duplicates="true"/>

 <file:inbound-channel-adapter id="filesIn"
        directory="file:${input.directory}"
        filter="customFilterBean" />

 <file:inbound-channel-adapter id="filesIn"
        directory="file:${input.directory}"
        filename-pattern="test*" />               

The first channel adapter is relying on the default filter that just prevents duplication, the second is using a custom filter, and the third is using the filename-pattern attribute to add a AntPathMatcher based filter to the FileReadingMessageSource. The file-name-pattern and filter attributes are mutually exclusive, but you can use a CompositeFileListFilter to use any combination of filters, including a pattern based filter to fit your particular needs.

When multiple processes are reading from the same directory it can be desirable to lock files to prevent them from being picked up concurrently. To do this you can use a FileLocker. There is a java.nio based implementation available out of the box, but it is also possible to implement your own locking scheme. The nio locker can be injected as follows

 <file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory}" prevent-duplicates="true">
    <file:nio-locker/>
  </file:inbound-channel-adapter>
            

A custom locker you can configure like this:

 <file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory}" prevent-duplicates="true">
    <file:locker ref="customLocker"/>
  </file:inbound-channel-adapter>
            

When filtering and locking files is not enough it might be needed to control the way files are listed entirely. To implement this type of requirement you can use an implementation of DirectoryScanner. This scanner allows you to determine entirely what files are listed each poll. This is also the interface that Spring Integration uses internally to wire FileListFilters FileLocker to the FileReadingMessageSource. A custom DirectoryScanner can be injected into the <file:inbound-channel-adapter/> on the scanner attribute.

 <file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory}" prevent-duplicates="true" scanner="customDirectoryScanner"/>
            

This gives you full freedom to choose the ordering, listing and locking strategies.

To write messages to the file system you can use a FileWritingMessageHandler. This class can deal with File, String, or byte array payloads. In its simplest form the FileWritingMessageHandler only requires a destination directory for writing the files. The name of the file to be written is determined by the handler's FileNameGenerator. The default implementation looks for a Message header whose key matches the constant defined as FileHeaders.FILENAME.

Additionally, you can configure the encoding and the charset that will be used in case of a String payload.

To make things easier you can configure the FileWritingMessageHandler as part of an outbound channel adapter using the namespace.

 <file:outbound-channel-adapter id="filesOut" directory="file:${input.directory.property}"/>

The namespace based configuration also supports a delete-source-files attribute. If set to true, it will trigger deletion of the original source files after writing to a destination. The default value for that flag is false.

 <file:outbound-channel-adapter id="filesOut"
             directory="file:${output.directory}"
             delete-source-files="true"/>

In cases where you want to continue processing messages based on the written File you can use the outbound-gateway instead. It plays a very similar role as the outbound-channel-adapter. However after writing the File, it will also send it to the reply channel as the payload of a Message.

 <file:outbound-gateway id="mover" request-channel="moveInput"
            reply-channel="output"
            directory="${output.directory}"
            delete-source-files="true"/>

If you have more elaborate requirements or need to support additional payload types as input to be converted to file content you could extend the FileWritingMessageHandler, but a much better option is to rely on a Transformer.

To transform data read from the file system to objects and the other way around you need to do some work. Contrary to FileReadingMessageSource and to a lesser extent FileWritingMessageHandler, it is very likely that you will need your own mechanism to get the job done. For this you can implement the Transformer interface. Or extend the AbstractFilePayloadTransformer for inbound messages. Some obvious implementations have been provided.

FileToByteArrayTransformer transforms Files into byte[]s using Spring's FileCopyUtils. It is often better to use a sequence of transformers than to put all transformations in a single class. In that case the File to byte[] conversion might be a logical first step.

FileToStringTransformer will convert Files to Strings as the name suggests. If nothing else, this can be useful for debugging (consider using with a Wire Tap).

To configure File specific transformers you can use the appropriate elements from the file namespace.

 <file-to-bytes-transformer input-channel="input" output-channel="output"
             delete-files="true"/>

 <file:file-to-string-transformer input-channel="input" output-channel="output
             delete-files="true" charset="UTF-8"/>

The delete-files option signals to the transformer that it should delete the inbound File after the transformation is complete. This is in no way a replacement for using the AcceptOnceFileListFilter when the FileReadingMessageSource is being used in a multi-threaded environment (e.g. Spring Integration in general).