INT-2507: File: Fix HeadDirectoryScanner

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

When using a `HeadDirectoryScanner`, the use of any filter removed the
size limitation passed into the contstructor (or `queue-size` attribute
of a file inbound channel adapter.

The `HeadFilter` was overwritten.

Combine the head filter into a `CompositeFileListFilter` (creating one
if necessary).

src/reference/asciidoc/file.adoc

@@ -37,7 +37,7 @@ hidden files.
 
 [IMPORTANT]
 =====
-The `IgnoreHiddenFileListFilter` was introduced with _version 4.2_. In prior versions hidden files *were being picked up*.
+The `IgnoreHiddenFileListFilter` was introduced with _version 4.2_. In prior versions hidden files were included.
 With the default configuration, the `IgnoreHiddenFileListFilter` will be triggered first, then the `AcceptOnceFileListFilter`.
 =====
 
@@ -136,7 +136,7 @@ Therefore, you can also leave off the 2 attributes `prevent-duplicates` and `ign
 
 [IMPORTANT]
 =====
-The `ignore-hidden` attribute was introduced with _Spring Integration 4.2_. In prior versions hidden files *were being picked up*.
+The `ignore-hidden` attribute was introduced with _Spring Integration 4.2_. In prior versions hidden files were included.
 =====
 
 The second channel adapter example is using a custom filter, the third is using the _filename-pattern_ attribute to
@@ -187,6 +187,27 @@ IMPORTANT: It is important to understand that filters (including patterns, regex
 Any of these attributes set on the adapter are subsequently injected into the scanner.
 For this reason, if you need to provide a custom scanner and you have multiple file inbound adapters in the same application context, each adapter must be provided with its own instance of the scanner, either by declaring separate beans, or declaring `scope="prototype"` on the scanner bean so that the context will create a new instance for each use.
 
+===== Limiting Memory Consumption
+
+A `HeadDirectoryScanner` can be used to limit the number of files retained in memory.
+This can be useful when scanning large directories.
+With XML configuration, this is enabled using the `queue-size` property on the inbound channel adapter.
+
+Prior to _version 4.2_, this setting was incompatible with the use of any other filters.
+Any other filters (including `prevent-duplicates="true"`) overwrote the filter used to limit the size.
+
+[NOTE]
+=====
+The use of a `HeadDirectoryScanner` is incompatible with an `AcceptOnceFileListFilter`.
+Since all filters are consulted during the poll decision, the `AcceptOnceFileListFilter` does not know
+that other filters might be temporarily filtering files.
+Even if files that were previously filtered by the `HeadDirectoryScanner.HeadFilter` are now available, the
+`AcceptOnceFileListFilter` will filter them.
+
+Generally, instead of using an `AcceptOnceFileListFilter` in this case, one would simply remove the processed
+files so that the previously filtered files will be available on a future poll.
+=====
+
 [[file-tailing]]
 ==== 'Tail'ing Files
 

src/reference/asciidoc/whats-new.adoc

@@ -56,6 +56,8 @@ It is `true` by default.
 
 The `FileWritingMessageHandler` now also accepts `InputStream` as a valid message payload type.
 
+The `HeadDirectoryScanner` can now be used with other `FileListFilter` s.
+
 See <<files>> for more information.
 
 [[x4.2-class-package-change]]