[
https://issues.apache.org/jira/browse/IO-892?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18099604#comment-18099604
]
Xu Zhao commented on IO-892:
----------------------------
Thank you for the suggestion. I did consider a depth-aware FileFilter, but I
may be missing an intended integration point.
FileAlterationObserver currently calls directory.listFiles(fileFilter) for
each monitored directory. A FileFilter can reject entries below the depth
boundary, but the boundary directory is still listed and the filter is invoked
for every child. For a boundary directory containing 100,000 files, this still
performs the expensive directory enumeration during initialization and every
check cycle; it only prevents the returned children from being retained.
There is also a semantic distinction that a boolean FileFilter cannot express:
the directory at maxDepth should itself be accepted and monitored so its
create/change/delete events are preserved, while traversal into its children
should be skipped.
IOFileFilter has Path-based methods returning FileVisitResult, but
FileAlterationObserver currently stores a java.io.FileFilter and invokes it
through File.listFiles(FileFilter), so a SKIP_SUBTREE result is not available
at the traversal point.
That is why the current patch checks the depth before calling listFiles() at
all. The CountingFile test verifies that listFiles() is never invoked on a
directory at the boundary.
If you had a specialized traversal filter in mind—for example, a separate
predicate controlling whether an accepted directory should be descended into,
or an IOFileFilter/FileVisitResult integration—I can rework the proposal in
that direction. Would you prefer such a traversal-filter API over
Builder.setMaxDepth(int)?
> Add maximum traversal depth to FileAlterationObserver
> -----------------------------------------------------
>
> Key: IO-892
> URL: https://issues.apache.org/jira/browse/IO-892
> Project: Commons IO
> Issue Type: New Feature
> Reporter: Xu Zhao
> Priority: Major
>
> FileAlterationObserver currently traverses the complete directory tree during
> both initialization and every checkAndNotify() cycle. This can cause
> significant I/O, allocation, sorting, and retained-memory overhead when the
> observed tree contains directories with hundreds of thousands of entries.
> This proposal adds an optional maximum traversal depth through
> FileAlterationObserver.Builder.setMaxDepth(int).
> Proposed semantics:
> * The observed root directory has depth 0.
> * A maximum depth of 0 prevents listing entries below the root.
> * At greater depths, entries at the maximum depth are monitored.
> * Children of entries at the maximum depth are not listed and do not generate
> events.
> * The default is Integer.MAX_VALUE, preserving the current recursive behavior.
> * Negative values are rejected with IllegalArgumentException.
> The depth limit applies consistently during initialization and every
> subsequent checkAndNotify() cycle.
> The change is source and binary compatible because existing constructors and
> Builder usage retain unlimited recursion by default.
> Local Windows/NTFS measurements with 100,000 empty files below a depth-1
> boundary:
> || Mode || Initialization || Steady check average ||
> | Unlimited | 9069.894 ms | 8772.802 ms |
> | maxDepth=1 | 126.719 ms | 16.517 ms |
> The implementation includes tests for default compatibility, invalid values,
> depth boundaries, ignored events below the boundary, repeated check cycles,
> custom root entries, direct listFiles() invocation checks, and serialization
> round trips.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
