[
https://issues.apache.org/jira/browse/IO-812?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Gary D. Gregory updated IO-812:
-------------------------------
Description:
This ticket is only used to track Javadoc changes from IO-811.
JDK method Files.walk() clearly documents that the returned Stream<Path> must
be closed: "This method must be used within a try-with-resources statement or
similar control structure to ensure that the stream's open directories are
closed promptly after the stream's operations have completed." However, the
Commons IO methods that consume these streams fail to close them. And the
methods that pass on these streams fail to document that closing them is
required.
Problematic methods that I see:
* PathUtils.walk() lacks a documentation warning
* FilesUncheck.walk() both variants lack a documentation warning
* FileUtils.streamFiles() lacks a documentation warning
* FileUtils.listFiles() consumes a Files.walk() stream without closing it
* FileUtils.iterateFiles() claims to close the stream if the iterator is
consumed, however, in my test of consuming an iterator returned from this
method, a breakpoint set on FileTreeWalker.close() is never hit
Failing to close these streams can result in file handle leaks and other
problems, hence the importance of documenting and heading this requirement from
the JDK method.
was:
JDK method Files.walk() clearly documents that the returned Stream<Path> must
be closed: "This method must be used within a try-with-resources statement or
similar control structure to ensure that the stream's open directories are
closed promptly after the stream's operations have completed." However, the
Commons IO methods that consume these streams fail to close them. And the
methods that pass on these streams fail to document that closing them is
required.
Problematic methods that I see:
* PathUtils.walk() lacks a documentation warning
* FilesUncheck.walk() both variants lack a documentation warning
* FileUtils.streamFiles() lacks a documentation warning
* FileUtils.listFiles() consumes a Files.walk() stream without closing it
* FileUtils.iterateFiles() claims to close the stream if the iterator is
consumed, however, in my test of consuming an iterator returned from this
method, a breakpoint set on FileTreeWalker.close() is never hit
Failing to close these streams can result in file handle leaks and other
problems, hence the importance of documenting and heading this requirement from
the JDK method.
> Javadoc should mention closing Streams based on file resources
> --------------------------------------------------------------
>
> Key: IO-812
> URL: https://issues.apache.org/jira/browse/IO-812
> Project: Commons IO
> Issue Type: Bug
> Components: Utilities
> Affects Versions: 2.13.0
> Environment: Windows 11, Eclipse Adoptium OpenJDK 17.0.8.1+1
> Reporter: Adam Rauch
> Priority: Major
>
> This ticket is only used to track Javadoc changes from IO-811.
> JDK method Files.walk() clearly documents that the returned Stream<Path> must
> be closed: "This method must be used within a try-with-resources statement or
> similar control structure to ensure that the stream's open directories are
> closed promptly after the stream's operations have completed." However, the
> Commons IO methods that consume these streams fail to close them. And the
> methods that pass on these streams fail to document that closing them is
> required.
> Problematic methods that I see:
> * PathUtils.walk() lacks a documentation warning
> * FilesUncheck.walk() both variants lack a documentation warning
> * FileUtils.streamFiles() lacks a documentation warning
> * FileUtils.listFiles() consumes a Files.walk() stream without closing it
> * FileUtils.iterateFiles() claims to close the stream if the iterator is
> consumed, however, in my test of consuming an iterator returned from this
> method, a breakpoint set on FileTreeWalker.close() is never hit
> Failing to close these streams can result in file handle leaks and other
> problems, hence the importance of documenting and heading this requirement
> from the JDK method.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
