jcmdline
Class AbstractParameter

java.lang.Object
  extended byjcmdline.AbstractParameter
All Implemented Interfaces:
Parameter
Direct Known Subclasses:
BooleanParam, DateParam, DateTimeParam, FileParam, IntParam, StringParam, TimeParam

public abstract class AbstractParameter
extends java.lang.Object
implements Parameter

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 {
 
     private int length;
 
     public FixedLenParam(String tag, String desc, int length) {
         setTag(tag);
         setDesc(desc);
         this.length = length;
         setOptionLabel("<s>");
     }
 
     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:
jcmdline Rel. 1.0.3 $Id: AbstractParameter.java,v 1.2 2002/12/07 14:22:06 lglawrence Exp $
Author:
Lynne Lawrence

Field Summary
protected  java.lang.String[] 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 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 addValue(java.lang.String value)
          Adds the specified string as a value for this entity after calling validateValue() to validate.
 java.lang.String[] 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
 java.lang.String getValue()
          The value of the parameter, in the case where the parameter is not multi-valued.
 java.util.Collection getValues()
          gets the values associated with this Parameter
 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 vals)
          Sets the values that are acceptable for this parameter, if a restricted set exists.
 void setAcceptableValues(java.lang.String[] 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(java.lang.String value)
          Sets the value of the parameter to the specified string after calling validateValue() to validate.
 void setValues(java.util.Collection values)
          Sets the values of the parameter to those specified after calling validateValue() to validate.
 void setValues(java.lang.String[] values)
          Sets the values of the parameter to those specified after calling validateValue() to validate.
 void validateValue(java.lang.String value)
          Verifies that value is valid for this entity.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

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


optional

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


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.


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


set

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


values

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


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()

acceptableValues

protected java.lang.String[] acceptableValues
a set of restricted values the Parameter may take

See Also:
setAcceptableValues(), getAcceptableValues()

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()
Constructor Detail

AbstractParameter

public AbstractParameter()
Method Detail

isSet

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

Specified by:
isSet in interface Parameter
Returns:
true if the parameter's value has been set, false otherwise

setHidden

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

Specified by:
setHidden in interface Parameter
Parameters:
hidden - true (Parameter.HIDDEN) if the parameter is a hidden parameter

isHidden

public boolean isHidden()
gets the value of the hidden indicator

Specified by:
isHidden in interface Parameter
Returns:
true (Parameter.HIDDEN) if the parameter is a hidden parameter

setDesc

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

Specified by:
setDesc in interface Parameter
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.

getDesc

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

Specified by:
getDesc in interface Parameter
Returns:
this parameter's description

setTag

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

Specified by:
setTag in interface Parameter
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.

getTag

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

Specified by:
getTag in interface Parameter
Returns:
a unique identifier for this parameter
See Also:
setTag()

setMultiValued

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

Specified by:
setMultiValued in interface Parameter
Parameters:
multiValued - true if the parameter can have multiple values

isMultiValued

public boolean isMultiValued()
gets the value of multiValued indicator

Specified by:
isMultiValued in interface Parameter
Returns:
true if the parameter can have multiple values

setOptional

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

Specified by:
setOptional in interface Parameter
Parameters:
optional - true if the parameter is optional

isOptional

public boolean isOptional()
returns the value of the optional indicator

Specified by:
isOptional in interface Parameter
Returns:
true if the parameter is optional

getAcceptableValues

public java.lang.String[] 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.

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

setAcceptableValues

public void setAcceptableValues(java.lang.String[] 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.

Specified by:
setAcceptableValues in interface Parameter
Parameters:
vals - the new acceptable values
See Also:
getAcceptableValues()

setAcceptableValues

public void setAcceptableValues(java.util.Collection 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.

Specified by:
setAcceptableValues in interface Parameter
Parameters:
vals - the new acceptable values

addValue

public void addValue(java.lang.String value)
              throws CmdLineException
Adds the specified string as a value for this entity after calling validateValue() to validate.

Specified by:
addValue in interface 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 validateValue() detects a problem.

setValue

public void setValue(java.lang.String value)
              throws CmdLineException
Sets the value of the parameter to the specified string after calling validateValue() to validate.

Specified by:
setValue in interface Parameter
Parameters:
value - the new value of the parameter
Throws:
if - validateValue() detects a problem.
CmdLineException

setValues

public void setValues(java.util.Collection values)
               throws CmdLineException
Sets the values of the parameter to those specified after calling validateValue() to validate.

Specified by:
setValues in interface Parameter
Parameters:
values - A collection of String objects to be used as the parameter's values.
Throws:
java.lang.ClassCastException - if the Collection contains object that are not Strings.
CmdLineException - if more than one value is specified and multiValued is not true, or if validateValue() detects a problem.

setValues

public void setValues(java.lang.String[] values)
               throws CmdLineException
Sets the values of the parameter to those specified after calling validateValue() to validate.

Specified by:
setValues in interface Parameter
Parameters:
values - The String 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 validateValue() detects a problem.

validateValue

public void validateValue(java.lang.String value)
                   throws CmdLineException
Verifies that value is valid for this entity.

The implementation in AbstractParameter is to verify that, if there are specific acceptableValues associated with the Parameter, the value is one of those specified. Any additional validation must be done by a subclass. Because the validation performed by this method is applicable to most, if not all Parameters, it is recommended that subclasses call it from within their override methods:

 public void validateValue(String value) throws CmdLineException {
    super.validateValue(value);
    // do some subclass-specific validation
    .
    .
 }
 

Specified by:
validateValue in interface Parameter
Parameters:
value - the value to be validated
Throws:
CmdLineException - if value is not valid.

getValue

public java.lang.String 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.

Specified by:
getValue in interface Parameter
Returns:
The value of the parameter as a String, or null if the paramter has not been set.
See Also:
getValues()

getValues

public java.util.Collection getValues()
gets the values associated with this Parameter

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

setOptionLabel

public 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.

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

getOptionLabel

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

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

setIgnoreRequired

public 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".

Specified by:
setIgnoreRequired in interface Parameter
Parameters:
ignoreRequired - set to true to ignore missing required Parameters if this Parameter is set
See Also:
getIgnoreRequired()

getIgnoreRequired

public 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".

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