Xu Zhao created IO-892:
--------------------------
Summary: 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
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)
