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 cf22582e Javadoc: Fix swapped '@' and '+' descriptions in
PatternOptionBuilder (#446)
cf22582e is described below
commit cf22582e4e11053668ee748670b8130716c98c3c
Author: Andrea Cosentino <[email protected]>
AuthorDate: Thu Oct 29 12:34:24 2026 +0100
Javadoc: Fix swapped '@' and '+' descriptions in PatternOptionBuilder (#446)
* Javadoc: Fix swapped '@' and '+' descriptions in PatternOptionBuilder
The table in the PatternOptionBuilder Javadoc had '@' and '+' the wrong
way round. '@' is the code that creates an object through the no-arg
constructor of the named class, while '+' only loads the class; the
existing tests already check it that way.
While at it, note in Converter.OBJECT, Converter.CLASS,
TypeHandler.createObject() and TypeHandler.createClass() that they load
whatever class the value names, so they shouldn't be used on values
from an untrusted source.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
* Update src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
Co-authored-by: Gary Gregory <[email protected]>
* Update src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
Co-authored-by: Gary Gregory <[email protected]>
---------
Co-authored-by: Claude Opus 5.5 <[email protected]>
Co-authored-by: Gary Gregory <[email protected]>
---
src/main/java/org/apache/commons/cli/Converter.java | 8 ++++++++
src/main/java/org/apache/commons/cli/PatternOptionBuilder.java | 10 ++++++++--
src/main/java/org/apache/commons/cli/TypeHandler.java | 7 +++++++
3 files changed, 23 insertions(+), 2 deletions(-)
diff --git a/src/main/java/org/apache/commons/cli/Converter.java
b/src/main/java/org/apache/commons/cli/Converter.java
index d655205e..a5e9c9b8 100644
--- a/src/main/java/org/apache/commons/cli/Converter.java
+++ b/src/main/java/org/apache/commons/cli/Converter.java
@@ -46,6 +46,10 @@ public interface Converter<T, E extends Exception> {
/**
* Converts a String to a {@link Class}. Calls {@link
Class#forName(String, boolean, ClassLoader)} with {@code initialize} set to
{@code false} so that
* resolving the name does not by itself trigger the class's static
initializer.
+ * <p>
+ * The value can name any class visible to the class loader of this
library. Do not apply this converter, the default for options of type {@link
Class},
+ * to values from an untrusted source.
+ * </p>
*/
Converter<Class<?>, ClassNotFoundException> CLASS = s -> Class.forName(s,
false, Converter.class.getClassLoader());
@@ -66,6 +70,10 @@ public interface Converter<T, E extends Exception> {
/**
* Converts a class name to an instance of the class. Uses the Class
converter to find the class and then call the default constructor.
+ * <p>
+ * Creating the instance initializes the named class and runs its public
no-argument constructor, so the value decides which code runs. Do not apply this
+ * converter, the default for options of type {@link Object}, to values
from an untrusted source.
+ * </p>
*
* @see #CLASS
*/
diff --git a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
index f68cfaea..1cecc68b 100644
--- a/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
+++ b/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
@@ -35,7 +35,7 @@ import java.util.Map;
* </tr>
* <tr>
* <td>b@</td>
- * <td>-b [class name]</td>
+ * <td>-b [class name] (creates object via public no-argument constructor)</td>
* </tr>
* <tr>
* <td>c></td>
@@ -43,7 +43,7 @@ import java.util.Map;
* </tr>
* <tr>
* <td>d+</td>
- * <td>-d [class name] (creates object via empty constructor)</td>
+ * <td>-d [class name]</td>
* </tr>
* <tr>
* <td>e%</td>
@@ -69,6 +69,12 @@ import java.util.Map;
* </pre>
*
* <p>
+ * When a converted option value is retrieved, for example through {@link
CommandLine#getParsedOptionValue(String)}, the {@code @} and {@code +} codes
+ * load the class named by the option value, and {@code @} also creates an
instance by calling its public no-argument constructor. Do not use these codes
+ * for values from an untrusted source.
+ * </p>
+ *
+ * <p>
* TODO These need to break out to OptionType and also to be pluggable.
* </p>
*/
diff --git a/src/main/java/org/apache/commons/cli/TypeHandler.java
b/src/main/java/org/apache/commons/cli/TypeHandler.java
index 4709c781..8fe815b2 100644
--- a/src/main/java/org/apache/commons/cli/TypeHandler.java
+++ b/src/main/java/org/apache/commons/cli/TypeHandler.java
@@ -49,6 +49,9 @@ public class TypeHandler {
/**
* Returns the class whose name is {@code className}.
+ * <p>
+ * Do not pass a class name from an untrusted source, see {@link
Converter#CLASS}.
+ * </p>
*
* @param className The class name.
* @return The class if it is found.
@@ -124,6 +127,10 @@ public class TypeHandler {
/**
* Creates an Object from the class name and empty constructor.
+ * <p>
+ * This initializes the named class and runs its public no-argument
constructor. Do not pass a class name from an untrusted source, see
+ * {@link Converter#OBJECT}.
+ * </p>
*
* @param className The argument value.
* @return The initialized object.
