(commons-cli) branch master updated: Javadoc: Document how FileInputStream option values are opened (#448)

[ggregory]

This is an automated email from the ASF dual-hosted git repository.

garydgregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-cli.git


The following commit(s) were added to refs/heads/master by this push:
     new 1abdc3b8 Javadoc: Document how FileInputStream option values are 
opened (#448)
1abdc3b8 is described below

commit 1abdc3b8c9e15e51cab8cc2b4822222c01364ba7
Author: Andrea Cosentino <anco...@gmail.com>
AuthorDate: Thu Oct 29 12:40:24 2026 +0100

    Javadoc: Document how FileInputStream option values are opened (#448)
    
    The default FileInputStream converter, the '<' code in
    PatternOptionBuilder and TypeHandler.openFile() open the file as soon
    as the value is converted. The Javadoc didn't say that the caller has
    to close the stream, or that opening something like a named pipe
    blocks, just as new FileInputStream(String) does. Document both and add
    the missing '<' row to the PatternOptionBuilder table.
    
    Co-authored-by: Claude Opus 5.5 <nore...@anthropic.com>
---
 src/main/java/org/apache/commons/cli/PatternOptionBuilder.java | 4 ++++
 src/main/java/org/apache/commons/cli/TypeHandler.java          | 7 +++++++
 2 files changed, 11 insertions(+)

diff --git a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java 
b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
index 1cecc68b..ec7167a6 100644
--- a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
+++ b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
@@ -57,6 +57,10 @@ import java.util.Map;
  * <td>g:</td>
  * <td>-g [string]</td>
  * </tr>
+ * <tr>
+ * <td>h&lt;</td>
+ * <td>-h [file name] (opens the existing file for reading, the caller must 
close the stream)</td>
+ * </tr>
  * </table>
  *
  * <p>
diff --git a/src/main/java/org/apache/commons/cli/TypeHandler.java 
b/src/main/java/org/apache/commons/cli/TypeHandler.java
index 8fe815b2..cda551b6 100644
--- a/src/main/java/org/apache/commons/cli/TypeHandler.java
+++ b/src/main/java/org/apache/commons/cli/TypeHandler.java
@@ -36,6 +36,10 @@ import java.util.Objects;
  * Options with custom converters and/or verifiers, using the default 
serialization methods, this class should be properly configured with the custom 
converters
  * and verifiers for the specific class.
  * </p>
+ * <p>
+ * The default converter for {@link FileInputStream} opens the named file each 
time it converts a value, and the caller must close the returned stream. As
+ * with {@link FileInputStream#FileInputStream(String)}, opening a special 
file such as a named pipe can block.
+ * </p>
  */
 public class TypeHandler {
 
@@ -213,6 +217,9 @@ public class TypeHandler {
 
     /**
      * Returns the opened FileInputStream represented by {@code string}.
+     * <p>
+     * The caller must close the returned stream.
+     * </p>
      *
      * @param string The file location.
      * @return The file input stream represented by {@code string}.