spring-integration/spring-integration-reference/src/file.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="files">
	<title>Dealing with Files</title>

	<section id="file-intro">
		<title>Introduction</title>
		<para>
			Spring Integration File extends the Spring Integration Core with
			dedicated
			vocabulary to deal with reading, writing and transforming
			files.
			There is a namespace that enables elements that define channel
			adapters dedicated to files and support for transformers that
			transform files into strings or byte arrays. 
    	</para>
		<para>
			This section will explain the workings of <classname>PollableFileSource</classname>, <classname>FileWritingMessageConsumer</classname> and how to configure them as	<emphasis>beans</emphasis>. Also the support for dealing with files through file specific implementations of <interfacename>Transformer</interfacename> will be discussed. Finally the file specific namespace will be explained.
		</para>
	</section>

	<section id="file-reading">
		<title>Reading Files</title>
		<para>
			A <classname>PollableFileSource</classname> can be used to consume files from the filesystem. This is an implementation of <interfacename>PollableSource</interfacename> that creates messages from a file system directory.
			<programlisting language="xml"><![CDATA[<bean id="pollableFileSource" class="org.springframework.integration.file.PollableFileSource"
		p:inputDirectory="file:${input.directory.property}"/>]]></programlisting>
		</para>
		<para>
			To prevent creating messages for certain files, you may supply a
			{@link FileListFilter}. By default, an
			<classname>AcceptOnceFileListFilter</classname>
			is used. This filter ensures files are picked up only once from the
			directory.
			<programlisting language="xml"><![CDATA[<bean id="pollableFileSource" class="org.springframework.integration.file.PollableFileSource"
		p:inputDirectory="file:${input.directory.property}"
		p:filter-ref="customFilterBean"/>]]></programlisting>
		</para>
		<para>
			A common problem with reading files is that a file may be detected
			before it is ready. The default
			<classname>AcceptOnceFileListFilter
			</classname>
			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
			<classname>AcceptOnceFileListFilter
			</classname>
			allows for this.
			<programlisting language="xml"><![CDATA[	<bean id="pollableFileSource" class="org.springframework.integration.file.PollableFileSource"
		p:inputDirectory="file:${input.directory.property}"
		p:filter-ref="compositeFilter"/>
	<bean id="compositeFilter" class="org.springframework.integration.file.CompositeFileListFilter">
		<constructor-arg>
			<list>
				<bean class="org.springframework.integration.file.AcceptOnceFileListFilter" />
				<bean class="org.springframework.integration.file.PatternMatchingFileListFilter">
					<constructor-arg value="^test.*$"/>
				</bean>
			</list>
		</constructor-arg>
	</bean>]]></programlisting>
		</para>
		<para>
			The configuration can be simplified using the file specific
			namespace. To do this use the following template.
			<programlisting language="xml"><![CDATA[<?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-2.5.xsd
			http://www.springframework.org/schema/integration
			http://www.springframework.org/schema/integration/spring-integration-1.0.xsd
			http://www.springframework.org/schema/integration/file
			http://www.springframework.org/schema/integration/file/spring-integration-file-1.0.xsd">
</beans>]]></programlisting>
			Within this namespace you can reduce the PollableFileSource and wrap
			it in a InboundChannelAdapter like this:
			<programlisting language="xml"><![CDATA[<file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory.property}"/> 					(1)
<file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory.property}" 
       filter="customFilterBean" />							(2)
<file:inbound-channel-adapter id="filesIn"
       directory="file:${input.directory.property}" 
       filename-pattern="^test.*$" /> 							(3)]]></programlisting>
			Where (1) is relying on the default filter that just prevents
			duplication, (2) is using a custom filter and (3) is using the
			<emphasis>filename-pattern</emphasis>
			attribute to add a
			<classname>Pattern</classname>
			based filter to the
			<classname>PollableFileSource</classname>
		</para>
	</section>
	<section id="file-writing">
		<title>Writing files</title>
		<para>
			To write messages to the file system you can use a
			<classname>FileWritingMessageConsumer
			</classname>
			. This class can deal with File or byte[] payloads and otherwise
			invokes the toString() method on the payload to estabish the contents
			of the File. In its simplest form the
			<classname>FileWritingMessageConsumer
			</classname>
			just needs a parent directory for the files.
		</para>
		<para>
			Additionally, you can
			configure the encoding and the charset that
			will
			be used in case of a
			fallback on the toString() method.
		</para>
		<para>
			To make things easier you can configure the
			FileWritingMessageConsumer as part of an outbound channel adapter
			using the namespace.
			<programlisting language="xml"><![CDATA[	<file:outbound-channel-adapter id="filesOut" directory="file:${input.directory.property}"/>]]></programlisting>
		</para>
		<para>
			If you have more elaborate requirements to the payload to file
			conversion you could extend the FileWritingMessageConsumer, but a
			much better option is to rely on a
			<classname>Transformer</classname>
		</para>
	</section>
	<section id="file-transforming">
		<title>File Transformers</title>
		<para>
			<!-- Introduction -->
			To transform data read from the file system to objects and the other
			way around you need to do some work. Contrary to
			<classname>PollableFileSource</classname>
			and to a lesser extent
			<classname>FileWritingMessageConsumer
			</classname>
			it is very likely that you will need your own mechanism to get the
			job done. For this you can implement the
			<interfacename>Transformer</interfacename>
			interface. Or extend the
			<classname>AbstractFilePayloadTransformer
			</classname>
			for inbound messages. Some obvious implementations have been
			provided.
		</para>
		<para>
			<classname>FileToByteArrayTransformer
			</classname>
			transforms Files into byte[]s using
			<classname>FileCopyUtils</classname>
			. 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.
		</para>
		<para>
			<classname>FileToStringTransformer</classname>
			will convert Files to Strings as the name suggests. This is mainly useful for debugging.
		</para>
		<para>
			To configure File specific transformers you can use the appropriate
			elements from the file namespace.
			<programlisting language="xml"><![CDATA[<file-to-bytes-transformer input-channel="intput" output-channel="output" delete-files="true"/>]]></programlisting>
			The
			<emphasis>delete-files</emphasis>
			option signals the transformer to delete the File after the
			transformation is done. This is in no way a replacement for using the
			<classname>AcceptOnceFileListFilter
			</classname>
			with the PollableFileSource in a multi-threaded environment (e.g. Spring Integration in general).
		</para>
	</section>
</chapter>