jcmdline
Class StringParam

java.lang.Object
  extended by jcmdline.AbstractParameter<java.lang.String>
      extended by jcmdline.StringParam
All Implemented Interfaces:
Parameter<java.lang.String>

public class StringParam
extends AbstractParameter<java.lang.String>

Encapsulate a command line parameter whose value will be a string.

Usage:

 public class Sample {
     public static void main(String[] args) {
 
         // command line arguments
         StringParam patternArg =
             new StringParam("pattern", "the pattern to match",
                             StringParam.REQUIRED);
         // other param definitions omitted
         .
         .
         CmdLineHandler cl =
             new VersionCmdLineHandler("V 5.2",
             new HelpCmdLineHandler(helpText,
                 "kindagrep",
                 "find lines in files containing a specified pattern",
                 new Parameter[] { ignorecaseOpt, listfilesOpt },
                 new Parameter[] { patternArg, filesArg } ));
         cl.parse(args);
         .
         .
         // don't need to check patternArg.isSet() because is REQUIRED
         String pattern = patternArg.getValue();
 
 

Version:
jcmdline Rel. 2.0.0 $Id: StringParam.java,v 1.3 2005/02/06 23:42:23 lglawrence Exp $
Author:
Lynne Lawrence
See Also:
CmdLineParser

Field Summary
static java.lang.String DEFAULT_OPTION_LABEL
          the default label that will represent option values for this Parameter when displaying usage.
protected  int maxValLen
          the maximum acceptable string length for the parameter value - if not specified, defaults to StringParam.UNSPECIFIED_LENGTH, which permits the value to be any length.
protected  int minValLen
          the minimum acceptable string length for the parameter value - if not specified, defaults to 0.
static int UNSPECIFIED_LENGTH
          the value of the minimum or maximum length if they have not been explicitly specified.
 
Fields inherited from class jcmdline.AbstractParameter
acceptableValues, desc, hidden, ignoreRequired, multiValued, optional, optionLabel, set, tag, values
 
Fields inherited from interface jcmdline.Parameter
HIDDEN, MULTI_VALUED, OPTIONAL, PUBLIC, REQUIRED, SINGLE_VALUED
 
Constructor Summary
StringParam(java.lang.String tag, java.lang.String desc)
          constructor - creates single-valued, optional, parameter accepting a string value of any length
StringParam(java.lang.String tag, java.lang.String desc, boolean optional)
          constructor - creates single-valued, parameter accepting a string value of any length, and either optional or required, as specified.
StringParam(java.lang.String tag, java.lang.String desc, int minValLen, int maxValLen)
          constructor - creates a single-valued, optional, parameter accepting a value whose length is within the specified minimum and maximum lengths.
StringParam(java.lang.String tag, java.lang.String desc, int minValLen, int maxValLen, boolean optional)
          constructor - creates a single-valued, parameter accepting a value whose length is within the specified minimum and maximum lengths, and is optional or required, as specified.
StringParam(java.lang.String tag, java.lang.String desc, int minValLen, int maxValLen, boolean optional, boolean multiValued)
          constructor - creates a single-valued, parameter accepting a value whose length is within the specified minimum and maximum lengths, and optional and/or multi-valued, as specified
StringParam(java.lang.String tag, java.lang.String desc, int minValLen, int maxValLen, boolean optional, boolean multiValued, boolean hidden)
          constructor - creates a single-valued, parameter accepting a value whose length is within the specified minimum and maximum lengths, with all other options specified.
StringParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues)
          constructor - creates a single-valued, optional, string parameter whose value must be one of the specified values.
StringParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues, boolean optional)
          constructor - creates a single-valued, string parameter whose value must be a specified value, and which is optional or required, as specified.
StringParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues, boolean optional, boolean multiValued)
          constructor - creates a string parameter whose value must be a specified value and is optional and/or * multi-valued, as specified.
StringParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues, boolean optional, boolean multiValued, boolean hidden)
          constructor - creates a string parameter whose value must be a specified value and all other options are as specified.
 
Method Summary
 java.lang.String convertValue(java.lang.String strVal)
          Converts a String value to the type associated with the Parameter.
 int getMaxValLen()
          gets the value of the maximum acceptable length for the string value
 int getMinValLen()
          gets the value of the minimum acceptable length for the string value
 void setMaxLength(int maxValLen)
          Deprecated. This method deprecated in favor of setMaxValLen(), which is more in line with the naming convetions used elsewhere in this class.
 void setMaxValLen(int maxValLen)
          sets the value of the maximum acceptable length for the string value
 void setMinValLen(int minValLen)
          sets the value of the minimum acceptable length for the string value
 void validateValue(java.lang.String val)
          Validates a prospective value with regards to the minimum and maximum values and the acceptableValues - called by add/setValue(s)().
 
Methods inherited from class jcmdline.AbstractParameter
addStringValue, addValue, getAcceptableValues, getDesc, getIgnoreRequired, getOptionLabel, getTag, getValue, getValues, isHidden, isMultiValued, isOptional, isSet, setAcceptableValues, setAcceptableValues, setDesc, setHidden, setIgnoreRequired, setMultiValued, setOptional, setOptionLabel, setTag, setValue, setValues, setValues
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_OPTION_LABEL

public static final java.lang.String DEFAULT_OPTION_LABEL
the default label that will represent option values for this Parameter when displaying usage. The following demonstrates a possible usage excerpt for a StringParam option, where the option label is '<s>':
    suffix <s> Specifies the file suffix to use for all output files
               produced by this program.
 

See Also:
setOptionLabel(), "StringParam.defaultOptionLabel in 'strings' properties file"

UNSPECIFIED_LENGTH

public static final int UNSPECIFIED_LENGTH
the value of the minimum or maximum length if they have not been explicitly specified. This value may be compared with the results of getMinValLen() or getMaxValLen() to see whether a min/max had been set, but will cause an Exception to be thrown if passed to setMaxValLen() or setMinValLen().

See Also:
Constant Field Values

maxValLen

protected int maxValLen
the maximum acceptable string length for the parameter value - if not specified, defaults to StringParam.UNSPECIFIED_LENGTH, which permits the value to be any length.


minValLen

protected int minValLen
the minimum acceptable string length for the parameter value - if not specified, defaults to 0.

Constructor Detail

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc)
constructor - creates single-valued, optional, parameter accepting a string value of any length

Parameters:
tag - a unique identifier for this parameter
desc - a description of the parameter, suitable for display in a usage statement
Throws:
java.lang.IllegalArgumentException - if tag or are invalid.
See Also:
setTag(), setDesc()

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   boolean optional)
constructor - creates single-valued, parameter accepting a string value of any length, and either optional or required, as specified.

Parameters:
tag - a unique identifier for this parameter
desc - a description of the parameter, suitable for display in a usage statement
optional - OPTIONAL if optional, REQUIRED if required
Throws:
java.lang.IllegalArgumentException - if any of the specified parameters are invalid.
See Also:
setTag(), setDesc()

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   int minValLen,
                   int maxValLen)
constructor - creates a single-valued, optional, parameter accepting a value whose length is within the specified minimum and maximum lengths.

Parameters:
tag - a unique identifier for this parameter
desc - a description of the parameter, suitable for display in a usage statement
minValLen - the minimum acceptable length
maxValLen - the maximum acceptable length, or a negative number if there is no maximum length limit
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setMinValLen(), setMaxValLen()

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   int minValLen,
                   int maxValLen,
                   boolean optional)
constructor - creates a single-valued, parameter accepting a value whose length is within the specified minimum and maximum lengths, and is optional or required, as specified.

Parameters:
tag - a unique identifier for this parameter
desc - a description of the parameter, suitable for display in a usage statement
minValLen - the minimum acceptable length
maxValLen - the maximum acceptable length, or a negative number if there is no maximum length limit
optional - OPTIONAL if optional, REQUIRED if required
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setMinValLen(), setMaxValLen(), OPTIONAL, REQUIRED

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   int minValLen,
                   int maxValLen,
                   boolean optional,
                   boolean multiValued)
constructor - creates a single-valued, parameter accepting a value whose length is within the specified minimum and maximum lengths, and optional and/or multi-valued, as specified

Parameters:
tag - a unique identifier for this parameter
desc - a description of the parameter, suitable for display in a usage statement
minValLen - the minimum acceptable length
maxValLen - the maximum acceptable length, or a negative number if there is no maximum length limit
optional - OPTIONAL if optional, REQUIRED if required
multiValued - MULTI_VALUED if the parameter can accept multiple values, SINGLE_VALUED if the parameter can contain only a single value
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setMinValLen(), setMaxValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   int minValLen,
                   int maxValLen,
                   boolean optional,
                   boolean multiValued,
                   boolean hidden)
constructor - creates a single-valued, parameter accepting a value whose length is within the specified minimum and maximum lengths, with all other options specified.

Parameters:
tag - a unique identifier for this parameter
desc - a description of the parameter, suitable for display in a usage statement
minValLen - the minimum acceptable length
maxValLen - the maximum acceptable length, or a negative number if there is no maximum length limit
optional - OPTIONAL if optional, REQUIRED if required
multiValued - MULTI_VALUED if the parameter can accept multiple values, SINGLE_VALUED if the parameter can contain only a single value
hidden - HIDDEN if parameter is not to be listed in the usage, PUBLIC otherwise.
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setMinValLen(), setMaxValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   java.lang.String[] acceptableValues)
constructor - creates a single-valued, optional, string parameter whose value must be one of the specified values.

Parameters:
tag - the tag associated with this parameter
desc - a description of the parameter, suitable for display in a usage statement
acceptableValues - the acceptable values for the parameter
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setAcceptableValues(), setMinValLen()

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   java.lang.String[] acceptableValues,
                   boolean optional)
constructor - creates a single-valued, string parameter whose value must be a specified value, and which is optional or required, as specified.

Parameters:
tag - the tag associated with this parameter
desc - a description of the parameter, suitable for display in a usage statement
acceptableValues - the acceptable values for the parameter
optional - OPTIONAL if optional, REQUIRED if required
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setAcceptableValues(), setMinValLen(), OPTIONAL, REQUIRED

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   java.lang.String[] acceptableValues,
                   boolean optional,
                   boolean multiValued)
constructor - creates a string parameter whose value must be a specified value and is optional and/or * multi-valued, as specified.

Parameters:
tag - the tag associated with this parameter
desc - a description of the parameter, suitable for display in a usage statement
acceptableValues - the acceptable values for the parameter
optional - OPTIONAL if optional, REQUIRED if required
multiValued - MULTI_VALUED if the parameter can accept multiple values, SINGLE_VALUED if the parameter can contain only a single value
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setAcceptableValues(), setMinValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED

StringParam

public StringParam(java.lang.String tag,
                   java.lang.String desc,
                   java.lang.String[] acceptableValues,
                   boolean optional,
                   boolean multiValued,
                   boolean hidden)
constructor - creates a string parameter whose value must be a specified value and all other options are as specified.

Parameters:
tag - the tag associated with this parameter
desc - a description of the parameter, suitable for display in a usage statement
acceptableValues - the acceptable values for the parameter
optional - OPTIONAL if optional, REQUIRED if required
multiValued - MULTI_VALUED if the parameter can accept multiple values, SINGLE_VALUED if the parameter can contain only a single value
hidden - HIDDEN if parameter is not to be listed in the usage, PUBLIC otherwise.
Throws:
java.lang.IllegalArgumentException - if any parameter is invalid.
See Also:
setTag(), setDesc(), setAcceptableValues(), setMinValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC
Method Detail

convertValue

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

Specified by:
convertValue in class AbstractParameter<java.lang.String>
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
See Also:
AbstractParameter.convertValue(java.lang.String)

getMaxValLen

public int getMaxValLen()
gets the value of the maximum acceptable length for the string value

Returns:
The maximum acceptable length for string value. This will be equal to StingParam.UNSPECIFIED_LENGTH if it had never been set.

getMinValLen

public int getMinValLen()
gets the value of the minimum acceptable length for the string value

Returns:
the minimum acceptable length for string value This will be equal to 0 if it had never been set.

setMaxLength

public void setMaxLength(int maxValLen)
Deprecated. This method deprecated in favor of setMaxValLen(), which is more in line with the naming convetions used elsewhere in this class.

sets the value of the maximum acceptable length for the string value

Parameters:
maxValLen - the maximum acceptable length
Throws:
java.lang.IllegalArgumentException - if maxValLen less than 0, or is less than minValLen .
See Also:
setMaxValLen()

setMaxValLen

public void setMaxValLen(int maxValLen)
sets the value of the maximum acceptable length for the string value

Parameters:
maxValLen - the maximum acceptable length
Throws:
java.lang.IllegalArgumentException - if maxValLen less than 0, or is less than minValLen .

setMinValLen

public void setMinValLen(int minValLen)
sets the value of the minimum acceptable length for the string value

Parameters:
minValLen - the minimum acceptable length
Throws:
java.lang.IllegalArgumentException - if minValLen less than 0, or is greater than maxValLen .

validateValue

public void validateValue(java.lang.String val)
                   throws CmdLineException
Validates a prospective value with regards to the minimum and maximum values and the acceptableValues - called by add/setValue(s)().

Overrides:
validateValue in class AbstractParameter<java.lang.String>
Parameters:
val - the prospective value to validate
Throws:
CmdLineException - if value is not valid with regard to the minimum and maximum lengths, and the acceptableValues.