From 97b59c2acda102610a973cc9f2a07af953b6043a Mon Sep 17 00:00:00 2001 From: Gunnar Hillert Date: Thu, 14 Jun 2012 17:56:19 -0400 Subject: [PATCH] INT-2618 - Document directory-expression attribute * Add documentation directory-expression * Add documentation for auto-create-directory attribute * Refactor File Adapter chapter slightly so that it flows better For reference see: https://jira.springsource.org/browse/INT-2618 INT-2618 - Doc updated due to changes in INT-805 * rebased * clarified the file section in the reference doc --- .../config/spring-integration-file-2.2.xsd | 13 +- src/reference/docbook/file.xml | 231 ++++++++++++------ 2 files changed, 168 insertions(+), 76 deletions(-) diff --git a/spring-integration-file/src/main/resources/org/springframework/integration/file/config/spring-integration-file-2.2.xsd b/spring-integration-file/src/main/resources/org/springframework/integration/file/config/spring-integration-file-2.2.xsd index 5c955f25b5..3f5bcd6144 100644 --- a/spring-integration-file/src/main/resources/org/springframework/integration/file/config/spring-integration-file-2.2.xsd +++ b/spring-integration-file/src/main/resources/org/springframework/integration/file/config/spring-integration-file-2.2.xsd @@ -286,7 +286,7 @@ Only files matching this regular expression will be picked up by this adapter. Extension used when uploading files. We change it after we know it's uploaded. - This attribute is mutualy exclusive with 'append' since the append is done to the + This attribute is mutualy exclusive with 'append' since the append is done to the actual file and not its temporary counterpart. The default value of this attribute (i.e., .writing) is ignored when 'append' is set to true. @@ -295,10 +295,13 @@ Only files matching this regular expression will be picked up by this adapter. - Will append to the existing file if such file exists otherwise the new file will be created as usual - but once created the subsequent data will be appended to it. - This attribute is mutualy exclusive with the 'temporary-file-suffix' since append is done to the - actual file and not its temporary counterpart. + If set to 'true', the data will will be appended to the + existing file if such file exists, otherwise the new file + will be created as usual but once created the subsequent data + will be appended to it. This attribute is mutualy exclusive + with the 'temporary-file-suffix' since append is done to the + actual file and not its temporary counterpart. This attribute + defaults to 'false' if not set explicitly. diff --git a/src/reference/docbook/file.xml b/src/reference/docbook/file.xml index 70eca1601f..faea42a270 100644 --- a/src/reference/docbook/file.xml +++ b/src/reference/docbook/file.xml @@ -54,7 +54,7 @@ class="org.springframework.integration.file.FileReadingMessageSource" p:inputDirectory="${input.directory}" p:filter-ref="compositeFilter"/> - @@ -100,7 +100,7 @@ directory="file:${input.directory}" filename-regex="test[0-9]+\.txt" /> ]]> - + The first channel adapter is relying on the default filter that just prevents duplication, the second is using a custom filter, the third is using the filename-pattern attribute to add an AntPathMatcher @@ -122,7 +122,7 @@ ]]> - + A custom locker you can configure like this: @@ -143,77 +143,166 @@ that Spring Integration uses internally to wire FileListFilters FileLocker to the FileReadingMessageSource. A custom DirectoryScanner can be injected into the <int-file:inbound-channel-adapter/> on the scanner attribute. - ]]> - - + + This gives you full freedom to choose the ordering, listing and locking strategies. - -
- Writing files - - 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. - ]]> - - - 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 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 - 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 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. - - - - Since Spring Integration version 2.2. you can append Message content to the existing file instead of creating a new - File each time. To do so set append attribute to ; - Note that this attribute is mutually exclusive with temporary-file-suffix attribute since when - appending content to the existing file the adapter no longer uses temporary file. - -
+
+ Writing files + + 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 or + Outbound Gateway using the provided XML namespace + support. + +
+ Specifying the Output Directory + + Both, the File Oubound Channel Adapter and + the File Outbound Gateway provide two + configuration attributes for specifying the output directory: + + + + directory + + + directory-expression + + + + The directory-expression attribute is available since + Spring Integration 2.2. + + Using the directory attribute + + When using the directory attribute, the output + directory will be set to a fixed value, that is set at + intialization time of the FileWritingMessageHandler. + If you don't specify this attribute, then you must use the + directory-expression attribute. + + Using the directory-expression attribute + + If you want to have full SpEL support you would choose the + directory-expression attribute. This attribute + accepts a SpEL expression that is evaluated for each message being + processed. Thus, you have full access to a Message's payload and + its headers to dynamically specify the output file directory. + + + The SpEL expression must resolve to either a String + or to java.io.File. Furthermore the resulting + String or File must + point to a directory. If you don't specify the + directory-expression attribute, then you + must set the directory attribute. + + Using the auto-create-directory attribute + + If the destination directory does not exists, yet, by default the + respective destination directory and any non-existing parent directories + are being created automatically. You can set the + auto-create-directory attribute to + false in order to prevent that. This attribute + applies to both, the directory and the + directory-expression attribute. + + + + When using the directory attribute and + auto-create-directory is false, + the following change was made starting with Spring Integration 2.2: + + + Instead of checking for the existence of the destination directory + at initialization time of the adapter, this check is now + performed for each message being processed. + + + Furthermore, if auto-create-directory is + true and the directory was deleted between the + processing of messages, the directory will be re-created for each + message being processed. + + +
+
+ Append to Files + + Since Spring Integration 2.2 you can append Message + content to the existing file instead of creating a new File each + time. To do so, set the append attribute + to true. Note that this attribute is mutually exclusive + with temporary-file-suffix attribute since + when appending content to the existing file, the adapter no longer + uses a temporary file. This attribute defaults to 'false' if not + set explicitly. + +
+
+ File Outbound Channel Adapter + ]]> + + The namespace based configuration also supports a delete-source-files attribute. + If set to true, it will trigger the 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 if the FileHeaders.ORIGINAL_FILE header + value contains either the source File instance or a String representing the original file path. + +
+
+ Outbound Gateway + + 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 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. + +
+
+>>>>>>> INT-2618 - Document directory-expression attribute
File Transformers @@ -244,7 +333,7 @@ ]]> - + 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