AbstractParameter (jcmdline 2.0.1 API)

java.lang.Object
- jcmdline.AbstractParameter<T>

All Implemented Interfaces:: Parameter<T>

Direct Known Subclasses:: BooleanParam, DateParam, DateTimeParam, FileParam, IntParam, StringParam, TimeParam

public abstract class AbstractParameter<T>
extends 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:

Implement a convertValue(String) method.
If the validateValue(Object) is not adequate (see the javadoc for this method), override it, perhaps calling super.validateValue() to also invoke the functionality of this class.
Implement constructors applicable for the new type of Parameter.
Call setOptionLabel() from the constructors to set a reasonable option label for the new type of parameter.

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

Fields
Modifier and Type	Field and Description
`protected List<T>`	`acceptableValues` a set of restricted values the Parameter may take
`protected 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 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 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 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

Constructors
Constructor and Description

AbstractParameter()

Constructors
Constructor and Description
`AbstractParameter()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addStringValue(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(String strVal)` Converts a String value to the type associated with the Parameter.
`List<T>`	`getAcceptableValues()` Gets the values that are acceptable for this parameter, if a restricted set exists.
`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.
`String`	`getOptionLabel()` gets the value of optionLabel
`String`	`getTag()` gets the value of tag
`T`	`getValue()` The value of the parameter, in the case where the parameter is not multi-valued.
`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(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(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(String optionLabel)` Sets the value of optionLabel.
`void`	`setTag(String tag)` sets the value of tag
`void`	`setValue(T value)` Sets the value of the parameter to the specified string.
`void`	`setValues(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 List<T> acceptableValues
```
    a set of restricted values the Parameter may take
    
    See Also:
    
    setAcceptableValues(), getAcceptableValues()
  - desc
```
protected 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 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 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 ArrayList<T> values
```
    the value(s) of the entity
- Constructor Detail
  - AbstractParameter
```
public AbstractParameter()
```
- Method Detail
  - addStringValue
```
public void addStringValue(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(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 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 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 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 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 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(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(String desc)
             throws 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:
    
    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(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(String tag)
            throws 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:
    
    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(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.

Class AbstractParameter<T>

Field Summary

Fields inherited from interface jcmdline.Parameter

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

acceptableValues

desc

hidden

ignoreRequired

multiValued

optional

optionLabel

set

tag

values

Constructor Detail

AbstractParameter

Method Detail

addStringValue

convertValue

addValue

getAcceptableValues

getDesc

getIgnoreRequired

getOptionLabel

getTag

getValue

getValues

isHidden

isMultiValued

isOptional

isSet

setAcceptableValues

setAcceptableValues

setDesc

setHidden

setIgnoreRequired

setMultiValued

setOptional

setOptionLabel

setTag

setValue

setValues

setValues

validateValue