jcmdline
Class AbstractParameter<T>

java.lang.Object
  extended by jcmdline.AbstractParameter<T>
All Implemented Interfaces:
Parameter<T>
Direct Known Subclasses:
BooleanParam, DateParam, DateTimeParam, FileParam, IntParam, StringParam, TimeParam

public abstract class AbstractParameter<T>
extends java.lang.Object
implements Parameter<T>

Base class for command line parameters.

To implement a concrete Parameter class by subclassing this class, the following should be done:

A simple Parameter class that accepts only strings of a specified length might look as follows:

 public class FixedLenParam extends AbstractParameter<String> {
 
        private int length;
 
        public FixedLenParam(String tag, String desc, int length) {
                setTag(tag);
                setDesc(desc);
                this.length = length;
                setOptionLabel("<s>");
        }
 
        public String convertValue(String strVal) {
                return strVal;
        }
 
        public void validateValue(String val) throws CmdLineException {
                super.validateValue(val); // check acceptable values, etc..
                if (val.length() != length) {
                        throw new CmdLineException(getTag() + " must be a string of "
                                        + length + " characters in length");
                }
 
        }
 }
 

Version:
$Id: AbstractParameter.java,v 1.4 2009/08/07 16:13:28 lglawrence Exp $
Author:
Lynne Lawrence

Field Summary
protected  java.util.List<T> acceptableValues
          a set of restricted values the Parameter may take
protected  java.lang.String desc
          a description of the parameter to be displayed in the usage
protected  boolean hidden
          indicates that the parameter is hidden and will not be displayed in the normal usage - default is false
protected  boolean ignoreRequired
          During parse, ignore missing required Parameters if this Parameter is set.
protected  boolean multiValued
          Indicates whether the parameter can have multiple values.
protected  boolean optional
          Indicates whether or not the parameter is optional.
protected  java.lang.String optionLabel
          The label that should be used for a Parameter option's value in the usage
protected  boolean set
          indicates that the value of the parameter has been set
protected  java.lang.String tag
          the tag which uniquely identifies the parameter, and will be used to identify the parameter on the command line if the parameter is used as an option
protected  java.util.ArrayList<T> values
          the value(s) of the entity
 
Fields inherited from interface jcmdline.Parameter
HIDDEN, MULTI_VALUED, OPTIONAL, PUBLIC, REQUIRED, SINGLE_VALUED
 
Constructor Summary
AbstractParameter()
           
 
Method Summary
 void addStringValue(java.lang.String value)
          Add a value to this Parameter.
 void addValue(T value)
          Adds the specified Object as a value for this entity - the Object will be validated with respect to the constraints of the Parameter.
abstract  T convertValue(java.lang.String strVal)
          Converts a String value to the type associated with the Parameter.
 java.util.List<T> getAcceptableValues()
          Gets the values that are acceptable for this parameter, if a restricted set exists.
 java.lang.String getDesc()
          gets the value of the parameter's description
 boolean getIgnoreRequired()
          Gets the flag indicating that during parse, missing required Parameters are ignored if this Parameter is set.
 java.lang.String getOptionLabel()
          gets the value of optionLabel
 java.lang.String getTag()
          gets the value of tag
 T getValue()
          The value of the parameter, in the case where the parameter is not multi-valued.
 java.util.List<T> getValues()
          gets the values associated with this Parameter - the List will be in the order the values were listed on the command line.
 boolean isHidden()
          gets the value of the hidden indicator
 boolean isMultiValued()
          gets the value of multiValued indicator
 boolean isOptional()
          returns the value of the optional indicator
 boolean isSet()
          gets an indicator that the parameter's value has been set
 void setAcceptableValues(java.util.Collection<T> vals)
          Sets the values that are acceptable for this parameter, if a restricted set exists.
 void setAcceptableValues(T[] vals)
          Sets the values that are acceptable for this parameter, if a restricted set exists.
 void setDesc(java.lang.String desc)
          sets the value of this parameter's description
 void setHidden(boolean hidden)
          sets the value of the hidden indicator
 void setIgnoreRequired(boolean ignoreRequired)
          Sets a flag such that during parse, missing required Parameters are ignored if this Parameter is set.
 void setMultiValued(boolean multiValued)
          sets the value of the multiValued indicator
 void setOptional(boolean optional)
          indicates whether or not the parameter is optional
 void setOptionLabel(java.lang.String optionLabel)
          Sets the value of optionLabel.
 void setTag(java.lang.String tag)
          sets the value of tag
 void setValue(T value)
          Sets the value of the parameter to the specified string.
 void setValues(java.util.List<T> values)
          Sets the values of the parameter to those specified.
 void setValues(T[] values)
          Sets the values of the parameter to those specified.
 void validateValue(T value)
          This implementation compares the value to the acceptable values if any have been defined.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

acceptableValues

protected java.util.List<T> acceptableValues
a set of restricted values the Parameter may take

See Also:
setAcceptableValues(), getAcceptableValues()

desc

protected java.lang.String desc
a description of the parameter to be displayed in the usage


hidden

protected boolean hidden
indicates that the parameter is hidden and will not be displayed in the normal usage - default is false


ignoreRequired

protected boolean ignoreRequired
During parse, ignore missing required Parameters if this Parameter is set. Typically used by Parameters that cause an action then call System.exit(), like "-help".

See Also:
setIgnoreRequired(), getIgnoreRequired()

multiValued

protected boolean multiValued
Indicates whether the parameter can have multiple values. The default is false, indicating that the parameter can only accept a single value.


optional

protected boolean optional
Indicates whether or not the parameter is optional. The default is true, indicating that the parameter is optional.


optionLabel

protected java.lang.String optionLabel
The label that should be used for a Parameter option's value in the usage

See Also:
setOptionLabel(), getOptionLabel()

set

protected boolean set
indicates that the value of the parameter has been set


tag

protected java.lang.String tag
the tag which uniquely identifies the parameter, and will be used to identify the parameter on the command line if the parameter is used as an option


values

protected java.util.ArrayList<T> values
the value(s) of the entity

Constructor Detail

AbstractParameter

public AbstractParameter()
Method Detail

addStringValue

public void addStringValue(java.lang.String value)
                    throws CmdLineException
Add a value to this Parameter. This implementation calls convertValue(String) to convert the String, then addValue(Object).

Specified by:
addStringValue in interface Parameter<T>
Parameters:
value - the value to be added
Throws:
CmdLineException - if the value of the entity has already been set and multiValued is not true, or if the value is not valid.
See Also:
Parameter.addStringValue(java.lang.String)

convertValue

public abstract T convertValue(java.lang.String strVal)
                        throws CmdLineException
Converts a String value to the type associated with the Parameter. All non-abstract subclasses must implement this method.

Parameters:
strVal - the String value of the Parameter
Returns:
the parameter value converted to the Object type with which the Parameter is associated
Throws:
CmdLineException - if the conversion cannot be made

addValue

public void addValue(T value)
              throws CmdLineException
Description copied from interface: Parameter
Adds the specified Object as a value for this entity - the Object will be validated with respect to the constraints of the Parameter.

Specified by:
addValue in interface Parameter<T>
Parameters:
value - the value to be added
Throws:
CmdLineException - if the value of the entity has already been set and multiValued is not true, or if the validation provided by the implementing class fails.
See Also:
Parameter.addValue(Object)

getAcceptableValues

public java.util.List<T> getAcceptableValues()
Description copied from interface: Parameter
Gets the values that are acceptable for this parameter, if a restricted set exists. If there is no restricted set of acceptable values, null is returned.

Specified by:
getAcceptableValues in interface Parameter<T>
Returns:
a set of acceptable values for the Parameter, or null if there is none.
See Also:
Parameter.getAcceptableValues()

getDesc

public java.lang.String getDesc()
Description copied from interface: Parameter
gets the value of the parameter's description

Specified by:
getDesc in interface Parameter<T>
Returns:
this parameter's description
See Also:
Parameter.getDesc()

getIgnoreRequired

public boolean getIgnoreRequired()
Description copied from interface: Parameter
Gets the flag indicating that during parse, missing required Parameters are ignored if this Parameter is set. Typically used by Parameters that cause an action then call System.exit(), like "-help".

Specified by:
getIgnoreRequired in interface Parameter<T>
Returns:
true if missing required Parameters will be ignored when this Parameter is set.
See Also:
Parameter.getIgnoreRequired()

getOptionLabel

public java.lang.String getOptionLabel()
Description copied from interface: Parameter
gets the value of optionLabel

Specified by:
getOptionLabel in interface Parameter<T>
Returns:
the string used as a label for the parameter's value
See Also:
Parameter.getOptionLabel()

getTag

public java.lang.String getTag()
Description copied from interface: Parameter
gets the value of tag

Specified by:
getTag in interface Parameter<T>
Returns:
a unique identifier for this parameter
See Also:
Parameter.getTag()

getValue

public T getValue()
Description copied from interface: Parameter
The value of the parameter, in the case where the parameter is not multi-valued. For a multi-valued parameter, the first value specified is returned.

Specified by:
getValue in interface Parameter<T>
Returns:
The value of the parameter, or null if the parameter has not been set.
See Also:
Parameter.getValue()

getValues

public java.util.List<T> getValues()
Description copied from interface: Parameter
gets the values associated with this Parameter - the List will be in the order the values were listed on the command line.

Specified by:
getValues in interface Parameter<T>
Returns:
The values associated with this Parameter. Note that this might be an empty List if the Parameter has not been set.
See Also:
Parameter.getValues()

isHidden

public boolean isHidden()
Description copied from interface: Parameter
gets the value of the hidden indicator

Specified by:
isHidden in interface Parameter<T>
Returns:
true (Parameter.HIDDEN) if the parameter is a hidden parameter
See Also:
Parameter.isHidden()

isMultiValued

public boolean isMultiValued()
Description copied from interface: Parameter
gets the value of multiValued indicator

Specified by:
isMultiValued in interface Parameter<T>
Returns:
true if the parameter can have multiple values
See Also:
Parameter.isMultiValued()

isOptional

public boolean isOptional()
Description copied from interface: Parameter
returns the value of the optional indicator

Specified by:
isOptional in interface Parameter<T>
Returns:
true if the parameter is optional
See Also:
Parameter.isOptional()

isSet

public boolean isSet()
Description copied from interface: Parameter
gets an indicator that the parameter's value has been set

Specified by:
isSet in interface Parameter<T>
Returns:
true if the parameter's value has been set, false otherwise
See Also:
Parameter.isSet()

setAcceptableValues

public void setAcceptableValues(java.util.Collection<T> vals)
Description copied from interface: Parameter
Sets the values that are acceptable for this parameter, if a restricted set exists. A null vals value, or an empty vals Collection, will result in any previously set acceptable values being cleared.

The toString() values of the Objects in vals will be used for the acceptable values.

Specified by:
setAcceptableValues in interface Parameter<T>
Parameters:
vals - the new acceptable values
See Also:
Parameter.setAcceptableValues(java.util.Collection)

setAcceptableValues

public void setAcceptableValues(T[] vals)
Description copied from interface: Parameter
Sets the values that are acceptable for this parameter, if a restricted set exists. A null vals value, or an empty vals array, will result in any previously set acceptable values being cleared.

Specified by:
setAcceptableValues in interface Parameter<T>
Parameters:
vals - the new acceptable values
See Also:
Parameter.setAcceptableValues(Collection)

setDesc

public void setDesc(java.lang.String desc)
             throws java.lang.IllegalArgumentException
Description copied from interface: Parameter
sets the value of this parameter's description

Specified by:
setDesc in interface Parameter<T>
Parameters:
desc - a description of the parameter, suitable for display in the command's usage
Throws:
java.lang.IllegalArgumentException - if desc is fewer than 5 charaters.
See Also:
Parameter.setDesc(java.lang.String)

setHidden

public void setHidden(boolean hidden)
Description copied from interface: Parameter
sets the value of the hidden indicator

Specified by:
setHidden in interface Parameter<T>
Parameters:
hidden - true (Parameter.HIDDEN) if the parameter is a hidden parameter
See Also:
Parameter.setHidden(boolean)

setIgnoreRequired

public void setIgnoreRequired(boolean ignoreRequired)
Description copied from interface: Parameter
Sets a flag such that during parse, missing required Parameters are ignored if this Parameter is set. Typically used by Parameters that cause an action then call System.exit(), like "-help".

Specified by:
setIgnoreRequired in interface Parameter<T>
Parameters:
ignoreRequired - set to true to ignore missing required Parameters if this Parameter is set
See Also:
Parameter.setIgnoreRequired(boolean)

setMultiValued

public void setMultiValued(boolean multiValued)
Description copied from interface: Parameter
sets the value of the multiValued indicator

Specified by:
setMultiValued in interface Parameter<T>
Parameters:
multiValued - true if the parameter can have multiple values
See Also:
Parameter.setMultiValued(boolean)

setOptional

public void setOptional(boolean optional)
Description copied from interface: Parameter
indicates whether or not the parameter is optional

Specified by:
setOptional in interface Parameter<T>
Parameters:
optional - true if the parameter is optional
See Also:
Parameter.setOptional(boolean)

setOptionLabel

public void setOptionLabel(java.lang.String optionLabel)
Description copied from interface: Parameter
Sets the value of optionLabel. This label will be used when the usage for the command is displayed. For instance, a date parameter might use "<mm/dd/yy>". This could then be displayed as in the following usage.
 st_date <mm/dd/yy>  the start date of the report
 
The default is the empty string.

Specified by:
setOptionLabel in interface Parameter<T>
Parameters:
optionLabel - The string used as a label for the parameter's value. If null, an empty string is used.
See Also:
Parameter.setOptionLabel(java.lang.String)

setTag

public void setTag(java.lang.String tag)
            throws java.lang.IllegalArgumentException
Description copied from interface: Parameter
sets the value of tag

Specified by:
setTag in interface Parameter<T>
Parameters:
tag - a unique identifier for this parameter. If the parameter is used as an option, it will be used to identify the option on the command line. In the case where the parameter is used as an argument, it will only be used to identify the argument in the usage statement. Tags must be made up of any character but '='.
Throws:
java.lang.IllegalArgumentException - if the length of tag is less than 1, or tag contains an invalid character.
See Also:
Parameter.setTag(java.lang.String)

setValue

public void setValue(T value)
              throws CmdLineException
Description copied from interface: Parameter
Sets the value of the parameter to the specified string.

Specified by:
setValue in interface Parameter<T>
Parameters:
value - the new value of the parameter
Throws:
CmdLineException - if the validation provided by the implementing class fails.
See Also:
Parameter.setValue(java.lang.Object)

setValues

public void setValues(java.util.List<T> values)
               throws CmdLineException
Description copied from interface: Parameter
Sets the values of the parameter to those specified.

Specified by:
setValues in interface Parameter<T>
Parameters:
values - A List of objects to be used as the parameter's values.
Throws:
CmdLineException - if more than one value is specified and multiValued is not true, or if the validation provided by the implementing class fails.
See Also:
Parameter.setValues(List)

setValues

public void setValues(T[] values)
               throws CmdLineException
Description copied from interface: Parameter
Sets the values of the parameter to those specified.

Specified by:
setValues in interface Parameter<T>
Parameters:
values - The objects to be used as the parameter's values.
Throws:
CmdLineException - if more than one value is specified and multiValued is not true, or if the validation provided by the implementing class fails.
See Also:
Parameter.setValues(Object[])

validateValue

public void validateValue(T value)
                   throws CmdLineException
This implementation compares the value to the acceptable values if any have been defined.

Parameters:
value - the value to be validated
Throws:
CmdLineException - if there are acceptable values defined and the value is not one of them.