jcmdline
Interface Parameter<T>

All Known Implementing Classes:
AbstractParameter, BooleanParam, DateParam, DateTimeParam, FileParam, IntParam, StringParam, TimeParam

public interface Parameter<T>

Interface for command line parameters.

Version:
jcmdline Rel. 2.0.0 $Id: Parameter.java,v 1.2 2002/12/07 14:22:06 lglawrence Exp $
Author:
Lynne Lawrence

Field Summary
static boolean HIDDEN
          when used as a value for the hidden indicator, indicates that a parameter is hidden, and its description will not be listed in the usage.
static boolean MULTI_VALUED
          when used as a value for the multiValued indicator, specifies that an parameter accepts mulitiple values
static boolean OPTIONAL
          when used as a value for the optional indicator, specifies that an parameter is optional
static boolean PUBLIC
          when used as a value for the hidden indicator, indicates that a parameter is public, and its description will be listed in the usage.
static boolean REQUIRED
          when used as a value for the optional indicator, specifies that an parameter is required
static boolean SINGLE_VALUED
          when used as a value for the multiValued indicator, specifies that a parameter accepts only one value
 
Method Summary
 void addStringValue(java.lang.String value)
          Adds the value, specified as a String.
 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.
 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.
 

Field Detail

HIDDEN

static final boolean HIDDEN
when used as a value for the hidden indicator, indicates that a parameter is hidden, and its description will not be listed in the usage.

See Also:
Constant Field Values

MULTI_VALUED

static final boolean MULTI_VALUED
when used as a value for the multiValued indicator, specifies that an parameter accepts mulitiple values

See Also:
Constant Field Values

OPTIONAL

static final boolean OPTIONAL
when used as a value for the optional indicator, specifies that an parameter is optional

See Also:
Constant Field Values

PUBLIC

static final boolean PUBLIC
when used as a value for the hidden indicator, indicates that a parameter is public, and its description will be listed in the usage.

See Also:
Constant Field Values

REQUIRED

static final boolean REQUIRED
when used as a value for the optional indicator, specifies that an parameter is required

See Also:
Constant Field Values

SINGLE_VALUED

static final boolean SINGLE_VALUED
when used as a value for the multiValued indicator, specifies that a parameter accepts only one value

See Also:
Constant Field Values
Method Detail

addStringValue

void addStringValue(java.lang.String value)
                    throws CmdLineException
Adds the value, specified as a String. The String will be converted to the correct type and validated.

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.

addValue

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

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.

getAcceptableValues

java.util.List<T> getAcceptableValues()
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.

Returns:
a set of acceptable values for the Parameter, or null if there is none.

getDesc

java.lang.String getDesc()
gets the value of the parameter's description

Returns:
this parameter's description

getIgnoreRequired

boolean getIgnoreRequired()
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".

Returns:
true if missing required Parameters will be ignored when this Parameter is set.

getOptionLabel

java.lang.String getOptionLabel()
gets the value of optionLabel

Returns:
the string used as a label for the parameter's value

getTag

java.lang.String getTag()
gets the value of tag

Returns:
a unique identifier for this parameter

getValue

T getValue()
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.

Returns:
The value of the parameter, or null if the parameter has not been set.
See Also:
getValues()

getValues

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.

Returns:
The values associated with this Parameter. Note that this might be an empty List if the Parameter has not been set.
See Also:
isSet()

isHidden

boolean isHidden()
gets the value of the hidden indicator

Returns:
true (HIDDEN) if the parameter is a hidden parameter

isMultiValued

boolean isMultiValued()
gets the value of multiValued indicator

Returns:
true if the parameter can have multiple values

isOptional

boolean isOptional()
returns the value of the optional indicator

Returns:
true if the parameter is optional

isSet

boolean isSet()
gets an indicator that the parameter's value has been set

Returns:
true if the parameter's value has been set, false otherwise

setAcceptableValues

void setAcceptableValues(java.util.Collection<T> vals)
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.

Parameters:
vals - the new acceptable values

setAcceptableValues

void setAcceptableValues(T[] vals)
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.

Parameters:
vals - the new acceptable values
See Also:
getAcceptableValues()

setDesc

void setDesc(java.lang.String desc)
             throws java.lang.IllegalArgumentException
sets the value of this parameter's description

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.

setHidden

void setHidden(boolean hidden)
sets the value of the hidden indicator

Parameters:
hidden - true (HIDDEN) if the parameter is a hidden parameter

setIgnoreRequired

void setIgnoreRequired(boolean ignoreRequired)
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".

Parameters:
ignoreRequired - set to true to ignore missing required Parameters if this Parameter is set
See Also:
getIgnoreRequired()

setMultiValued

void setMultiValued(boolean multiValued)
sets the value of the multiValued indicator

Parameters:
multiValued - true if the parameter can have multiple values

setOptional

void setOptional(boolean optional)
indicates whether or not the parameter is optional

Parameters:
optional - true if the parameter is optional

setOptionLabel

void setOptionLabel(java.lang.String optionLabel)
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.

Parameters:
optionLabel - The string used as a label for the parameter's value. If null, an empty string is used.
See Also:
getOptionLabel()

setTag

void setTag(java.lang.String tag)
            throws java.lang.IllegalArgumentException
sets the value of tag

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.

setValue

void setValue(T value)
              throws CmdLineException
Sets the value of the parameter to the specified string.

Parameters:
value - the new value of the parameter
Throws:
CmdLineException - if the validation provided by the implementing class fails.

setValues

void setValues(java.util.List<T> values)
               throws CmdLineException
Sets the values of the parameter to those specified.

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.

setValues

void setValues(T[] values)
               throws CmdLineException
Sets the values of the parameter to those specified.

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.