diff --git a/spring-integration-reference/src/file.xml b/spring-integration-reference/src/file.xml index 54775440ce..c414af80f9 100644 --- a/spring-integration-reference/src/file.xml +++ b/spring-integration-reference/src/file.xml @@ -6,54 +6,53 @@
Introduction - 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. + 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, 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. + 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.
Reading Files - 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. - FileReadingMessageSource can be used to consume files from the filesystem. + This is an implementation of MessageSource that creates messages from + a file system directory. ]]> + 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. + AcceptOnceFileListFilter is used. This filter + ensures files are picked up only once from the directory. ]]> - 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 + 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. + AcceptOnceFileListFilter allows for this. + The CompositeFileListFilter enables the + composition. @@ -67,8 +66,8 @@ ]]> - The configuration can be simplified using the file specific - namespace. To do this use the following template. + The configuration can be simplified using the file specific namespace. To do + this use the following template. ]]> Within this namespace you can reduce the FileReadingMessageSource and wrap - it in an InboundChannelAdapter like this: - - - ]]> - Where 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 - Pattern - based filter to the - FileReadingMessageSource + it in an inbound Channel Adapter like this: + + + + + ]]> + 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 Pattern + based filter to the FileReadingMessageSource.
+
Writing files To write messages to the file system you can use a - FileWritingMessageHandler - - . This class can deal with File or byte[] payloads and otherwise - invokes the toString() method on the payload to establish the contents - of the File. In its simplest form the - FileWritingMessageHandler - - just needs a parent directory for the files. + 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 - fallback on the toString() method. + 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. - ]]> + To make things easier you can configure the FileWritingMessageHandler as + part of an outbound channel adapter using the namespace. + ]]> - Namespace based configuration also supports delete-source-files attribute which if set to true - will trigger deletion of the original source files after writing to a destination. - The default value for that flag is false - ]]> + 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. + ]]> - The delete-source-files attribute will only have an effect if the inbound Message has a File payload or - FileHeaders.ORIGINAL_FILE header value containing either a File instance or a String representing the original file path. + The delete-source-files attribute will only have an effect if the inbound + Message has a File payload or if the FileHeaders.ORIGINAL_FILE header + value contains either the source File instance or a String representing the original file path. - In cases where you want to continue processing messages based on the written File you can use outbound-gateway which plays a very similar role - as the outbound-channel-adapter. However instead of writing a file It will send it over to the reply channel - ]]> + 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. + ]]> + + The 'outbound-gateway' works well in cases where you want to first move a File and then send it + through a processing pipeline. In such cases, you may connect the file namespace's + 'inbound-channel-adapter' element to the 'outbound-gateway' and then connect that gateway's + reply-channel to the beginning of the pipeline. + - If you have more elaborate requirements to the payload to file - conversion you could extend the FileWritingMessageHandler, but a - much better option is to rely on a - Transformer + 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.
+
File Transformers - - 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. + 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 - 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 + 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. This is mainly useful for debugging. + 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. - ]]> - The - delete-files - option signals the transformer to delete the File after the - transformation is done. This is in no way a replacement for using the - AcceptOnceFileListFilter - - with the PollableFileSource in a multi-threaded environment (e.g. Spring Integration in general). + To configure File specific transformers you can use the appropriate elements from the file namespace. + + + ]]> + 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).
+ \ No newline at end of file