INT-4231: Add FileExistsMode.REPLACE_IF_MODIFIED

JIRA: https://jira.spring.io/browse/INT-4231

For `FileWritingMessageHandler` and (S)FTP outbound gateways, support
`FileExistsMode.REPLACE_IF_MODIFIED` to allow overwriting an existing file if
the source file modified time is different to the existing file.

Polishing

src/reference/asciidoc/file.adoc

@@ -617,6 +617,7 @@ This behavior, though, can be changed by setting the _mode_ attribute on the res
 The following options exist:
 
 * REPLACE (Default)
+* REPLACE_IF_MODIFIED
 * APPEND
 * APPEND_NO_FLUSH
 * FAIL
@@ -631,6 +632,13 @@ _REPLACE_
 If the target file already exists, it will be overwritten.
 If the _mode_ attribute is not specified, then this is the default behavior when writing files.
 
+_REPLACE_IF_MODIFIED_
+
+If the target file already exists, it will be overwritten only if the last modified timestamp is different to the source file.
+For `File` payloads, the payload `lastModified` time is compared to the existing file.
+For other payloads, the `FileHeaders.SET_MODIFIED` (`file_setModified`) header is compared to the existing file.
+If the header is missing, or has a value that is not a `Number`, the file is always replaced.
+
 _APPEND_
 
 This mode allows you to append Message content to the existing file instead of creating a new file each time.

src/reference/asciidoc/ftp.adoc

@@ -848,12 +848,15 @@ _mget_ retrieves multiple remote files based on a pattern and supports the follo
 
 * -P - preserve the timestamps of the remote files
 
+* -R - retrieve the entire directory tree recursively
 
 * -x - Throw an exception if no files match the pattern (otherwise an empty list is returned)
 
 The message payload resulting from an _mget_ operation is a `List<File>` object - a List of File objects, each representing a retrieved file.
 
-The remote directory is provided in the `file_remoteDirectory` header, and the pattern for the file names is provided in the `file_remoteFile` header.
+The expression used to determine the remote path should produce a result that ends with `*` - e.g. `foo/*` will fetch the complete tree under `foo`.
+
+Starting with _version 5.0_, a recursive `MGET`, combined with the new `FileExistsMode.REPLACE_IF_MODIFIED` mode, can be used to periodically synchronize an entire remote directory tree locally.
 
 [NOTE]
 .Notes for when using recursion (`-R`)

src/reference/asciidoc/mongodb.adoc

@@ -410,4 +410,4 @@ private MongoDbOutboundGatewaySpec collectionCallbackOutboundGateway() {
             .collectionCallback(MongoCollection::count)
             .collectionName("foo");
     }
-----
+----

src/reference/asciidoc/security.adoc

@@ -183,4 +183,4 @@ public interface SecuredGateway {
     Future<String> send(String payload);
 
 }
-----
+----

src/reference/asciidoc/sftp.adoc

@@ -866,12 +866,15 @@ _mget_ retrieves multiple remote files based on a pattern and supports the follo
 
 * -P - preserve the timestamps of the remote files
 
+* -R - retrieve the entire directory tree recursively
 
 * -x - Throw an exception if no files match the pattern (otherwise an empty list is returned)
 
 The message payload resulting from an _mget_ operation is a `List<File>` object - a List of File objects, each representing a retrieved file.
 
-The remote directory is provided in the `file_remoteDirectory` header, and the pattern for the filenames is provided in the `file_remoteFile` header.
+The expression used to determine the remote path should produce a result that ends with `*` - e.g. `foo/*` will fetch the complete tree under `foo`.
+
+Starting with _version 5.0_, a recursive `MGET`, combined with the new `FileExistsMode.REPLACE_IF_MODIFIED` mode, can be used to periodically synchronize an entire remote directory tree locally.
 
 [NOTE]
 .Notes for when using recursion (`-R`)

src/reference/asciidoc/whats-new.adoc

@@ -69,6 +69,8 @@ See <<file-tailing>> for more information.
 The flush predicates for the `FileWritingMessageHandler` now have an additional parameter.
 See <<file-flushing>> for more information.
 
+The file outbound channel adapter (`FileWritingMessageHandler`) now supports the `REPLACE_IF_MODIFIED` `FileExistsMode`.
+
 ==== (S)FTP Changes
 
 The inbound channel adapters now have a property `max-fetch-size` which is used to limit the number of files fetched during a poll when there are no files currently in the local directory.
@@ -77,6 +79,9 @@ The regex and pattern filters can now be configured to always pass directories.
 This can be useful when using recursion in the outbound gateways.
 See <<ftp-outbound-gateway>> and <<sftp-outbound-gateway>> for more information.
 
+The FTP and SFTP outbound gateways now support the `REPLACE_IF_MODIFIED` `FileExistsMode` when fetching remote files.
+See <<ftp-outbound-gateway>> and <<sftp-outbound-gateway>> for more information.
+
 ==== Integration Properties
 
 Since _version 4.3.2_ a new `spring.integration.readOnly.headers` global property has been added to customize the list of headers which should not be copied to a newly created `Message` by the `MessageBuilder`.