zx8410-ops opened a new pull request, #870:
URL: https://github.com/apache/commons-io/pull/870
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to you under the Apache License, Version 2.0.
-->
Thanks for your contribution to [Apache
Commons](https://commons.apache.org/)!
- [x] Read the [contribution guidelines](CONTRIBUTING.md) for this project.
- [x] Read the [ASF Generative Tooling
Guidance](https://www.apache.org/legal/generative-tooling.html).
- [x] I used AI to create part of this pull request. OpenAI Codex assisted
with analysis, implementation, tests, local verification, and preparation of
this description.
- [ ] Run a successful build using the default Maven goal with `mvn`.
- [x] Write unit tests that match behavioral changes.
- [x] Write a detailed pull request description.
- [x] Each commit has a meaningful subject line and body.
## Summary
This PR adds an optional maximum traversal depth to `FileAlterationObserver`
through `Builder.setMaxDepth(int)`.
The observed root has depth 0. Setting `maxDepth` to 0 prevents listing
entries below the root. At greater depths, entries at `maxDepth` are monitored,
but their children are not listed and do not generate events.
The default remains `Integer.MAX_VALUE`, so existing builder usage and
deprecated constructors preserve full recursive monitoring. The depth limit
applies during both initialization and every `checkAndNotify()` cycle.
## Why this is not a FileFilter
A regular `FileFilter` cannot provide the same traversal behavior.
`FileAlterationObserver` calls `directory.listFiles(fileFilter)`, so a
depth-aware filter would still enumerate every child in a boundary directory.
It also cannot express "monitor this directory but do not descend into it" with
one boolean result.
This implementation checks the depth boundary before invoking `listFiles()`.
## Tests
Tests cover default compatibility, invalid values, boundary directory
events, ignored events below the boundary, repeated check cycles, verification
that `listFiles()` is not called below the boundary, custom root entries, and
serialization round trips.
Local Windows/NTFS results for 100,000 files below a depth-1 boundary:
| Mode | Initialize | Steady check average |
| --- | ---: | ---: |
| Unlimited | 9069.894 ms | 8772.802 ms |
| `maxDepth=1` | 126.719 ms | 16.517 ms |
Verification completed successfully:
- `mvn -q
"-Dtest=FileAlterationObserverTest,FileEntryTest,FileAlterationMonitorTest"
test`
- `mvn -q -DskipTests checkstyle:check javadoc:javadoc package japicmp:cmp`
- `git diff --check origin/master...HEAD`
JIRA: https://issues.apache.org/jira/browse/IO-892
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
