Author: tn
Date: Sun Feb 17 11:11:06 2013
New Revision: 1447005
URL: http://svn.apache.org/r1447005
Log:
[CLI-224] Add static builder methods to Option, check if at least one of
opt/longOpt has been specified, update javadoc.
Modified:
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/Option.java
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/OptionBuilder.java
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
commons/proper/cli/trunk/src/test/java/org/apache/commons/cli/OptionTest.java
Modified:
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/Option.java
URL:
http://svn.apache.org/viewvc/commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/Option.java?rev=1447005&r1=1447004&r2=1447005&view=diff
==============================================================================
--- commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/Option.java
(original)
+++ commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/Option.java
Sun Feb 17 11:11:06 2013
@@ -28,7 +28,8 @@ import java.util.List;
* this option, and a self-documenting description of the option.
* <p>
* An Option is not created independently, but is created through
- * an instance of {@link Options}.
+ * an instance of {@link Options}. An Option is required to have
+ * at least a short or a long-name.
* <p>
* <b>Note:</b> once an {@link Option} has been added to an instance
* of {@link Options}, it's required flag may not be changed anymore.
@@ -751,12 +752,38 @@ public class Option implements Cloneable
}
/**
+ * Returns a {@link Builder} to create an {@link Option} using descriptive
+ * methods.
+ *
+ * @return a new {@link Builder} instance
+ * @since 1.3
+ */
+ public static Builder builder()
+ {
+ return builder(null);
+ }
+
+ /**
+ * Returns a {@link Builder} to create an {@link Option} using descriptive
+ * methods.
+ *
+ * @param opt short representation of the option
+ * @return a new {@link Builder} instance
+ * @throws IllegalArgumentException if there are any non valid Option
characters in {@code opt}
+ * @since 1.3
+ */
+ public static Builder builder(final String opt)
+ {
+ return new Builder(opt);
+ }
+
+ /**
* A nested builder class to create <code>Option</code> instances
* using descriptive methods.
* <p>
* Example usage:
* <pre>
- * Option option = new Option.Builder("a", "Long description")
+ * Option option = Option.builder("a")
* .required(true)
* .longOpt("arg-name")
* .build();
@@ -764,13 +791,13 @@ public class Option implements Cloneable
*
* @since 1.3
*/
- public static class Builder
+ public static final class Builder
{
/** the name of the option */
private final String opt;
/** description of the option */
- private final String description;
+ private String description;
/** the long representation of the option */
private String longOpt;
@@ -794,28 +821,16 @@ public class Option implements Cloneable
private char valuesep;
/**
- * Constructs a new <code>Builder</code>.
- */
- public Builder()
- {
- this(null, null);
- }
-
- /**
* Constructs a new <code>Builder</code> with the minimum
* required parameters for an <code>Option</code> instance.
*
* @param opt short representation of the option
- * @param description describes the function of the option
- * @throws IllegalArgumentException if there are any non valid
- * Option characters in <code>opt</code>.
+ * @throws IllegalArgumentException if there are any non valid Option
characters in {@code opt}
*/
- public Builder(final String opt, final String description)
- throws IllegalArgumentException
+ private Builder(final String opt) throws IllegalArgumentException
{
OptionValidator.validateOption(opt);
this.opt = opt;
- this.description = description;
}
/**
@@ -829,7 +844,19 @@ public class Option implements Cloneable
this.argName = argName;
return this;
}
-
+
+ /**
+ * Sets the description for this option.
+ *
+ * @param description the description of the option.
+ * @return this builder, to allow method chaining
+ */
+ public Builder desc(final String description)
+ {
+ this.description = description;
+ return this;
+ }
+
/**
* Sets the long name of the Option.
*
@@ -918,12 +945,17 @@ public class Option implements Cloneable
}
/**
- * Constructs an Option.
+ * Constructs an Option with the values declared by this {@link
Builder}.
*
- * @return the new Option
+ * @return the new {@link Option}
+ * @throws IllegalArgumentException if neither {@code opt} or {@code
longOpt} has been set
*/
public Option build()
{
+ if (opt == null && longOpt == null)
+ {
+ throw new IllegalArgumentException("Either opt or longOpt must
be specified");
+ }
return new Option(this);
}
}
Modified:
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/OptionBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/OptionBuilder.java?rev=1447005&r1=1447004&r2=1447005&view=diff
==============================================================================
---
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/OptionBuilder.java
(original)
+++
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/OptionBuilder.java
Sun Feb 17 11:11:06 2013
@@ -27,7 +27,7 @@ package org.apache.commons.cli;
*
* @version $Id$
* @since 1.0
- * @deprecated since 1.3, use {@link Option.Builder} instead
+ * @deprecated since 1.3, use {@link Option.builder(String)} instead
*/
@Deprecated
public final class OptionBuilder
Modified:
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
URL:
http://svn.apache.org/viewvc/commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java?rev=1447005&r1=1447004&r2=1447005&view=diff
==============================================================================
---
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
(original)
+++
commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/PatternOptionBuilder.java
Sun Feb 17 11:11:06 2013
@@ -160,7 +160,7 @@ public class PatternOptionBuilder
{
if (opt != ' ')
{
- final Option option = new
Option.Builder(String.valueOf(opt), null)
+ final Option option = Option.builder(String.valueOf(opt))
.hasArg(type != null)
.required(required)
.type(type)
@@ -187,7 +187,7 @@ public class PatternOptionBuilder
if (opt != ' ')
{
- final Option option = new Option.Builder(String.valueOf(opt), null)
+ final Option option = Option.builder(String.valueOf(opt))
.hasArg(type != null)
.required(required)
.type(type)
Modified:
commons/proper/cli/trunk/src/test/java/org/apache/commons/cli/OptionTest.java
URL:
http://svn.apache.org/viewvc/commons/proper/cli/trunk/src/test/java/org/apache/commons/cli/OptionTest.java?rev=1447005&r1=1447004&r2=1447005&view=diff
==============================================================================
---
commons/proper/cli/trunk/src/test/java/org/apache/commons/cli/OptionTest.java
(original)
+++
commons/proper/cli/trunk/src/test/java/org/apache/commons/cli/OptionTest.java
Sun Feb 17 11:11:06 2013
@@ -153,36 +153,48 @@ public class OptionTest
{
char defaultSeparator = (char) 0;
- checkOption(new Option.Builder("a", "desc").build(),
+ checkOption(Option.builder("a").desc("desc").build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").build(),
+ checkOption(Option.builder("a").desc("desc").build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").longOpt("aaa").build(),
+ checkOption(Option.builder("a").desc("desc").longOpt("aaa").build(),
"a", "desc", "aaa", Option.UNINITIALIZED, null, false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").hasArg(true).build(),
+ checkOption(Option.builder("a").desc("desc").hasArg(true).build(),
"a", "desc", null, 1, null, false, false, defaultSeparator,
String.class);
- checkOption(new Option.Builder("a", "desc").hasArg(false).build(),
+ checkOption(Option.builder("a").desc("desc").hasArg(false).build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").hasArg(true).build(),
+ checkOption(Option.builder("a").desc("desc").hasArg(true).build(),
"a", "desc", null, 1, null, false, false, defaultSeparator,
String.class);
- checkOption(new Option.Builder("a", "desc").numberOfArgs(3).build(),
+ checkOption(Option.builder("a").desc("desc").numberOfArgs(3).build(),
"a", "desc", null, 3, null, false, false, defaultSeparator,
String.class);
- checkOption(new Option.Builder("a", "desc").required(true).build(),
+ checkOption(Option.builder("a").desc("desc").required(true).build(),
"a", "desc", null, Option.UNINITIALIZED, null, true, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").required(false).build(),
+ checkOption(Option.builder("a").desc("desc").required(false).build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").argName("arg1").build(),
+ checkOption(Option.builder("a").desc("desc").argName("arg1").build(),
"a", "desc", null, Option.UNINITIALIZED, "arg1", false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a",
"desc").optionalArg(false).build(),
+
checkOption(Option.builder("a").desc("desc").optionalArg(false).build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a", "desc").optionalArg(true).build(),
+ checkOption(Option.builder("a").desc("desc").optionalArg(true).build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, true,
defaultSeparator, String.class);
- checkOption(new Option.Builder("a",
"desc").valueSeparator(':').build(),
+
checkOption(Option.builder("a").desc("desc").valueSeparator(':').build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false, ':',
String.class);
- checkOption(new Option.Builder("a",
"desc").type(Integer.class).build(),
+
checkOption(Option.builder("a").desc("desc").type(Integer.class).build(),
"a", "desc", null, Option.UNINITIALIZED, null, false, false,
defaultSeparator, Integer.class);
}
+
+ @Test(expected=IllegalArgumentException.class)
+ public void testBuilderInsufficientParams1()
+ {
+ Option.builder().desc("desc").build();
+ }
+
+ @Test(expected=IllegalArgumentException.class)
+ public void testBuilderInsufficientParams2()
+ {
+ Option.builder(null).desc("desc").build();
+ }
private static void checkOption(Option option, String opt, String
description, String longOpt, int numArgs,
String argName, boolean required, boolean
optionalArg,
