jcmdline

Class StringParam

java.lang.Object

jcmdline.AbstractParameter<String>

jcmdline.StringParam

All Implemented Interfaces:

Parameter<String>

public class StringParam
extends AbstractParameter<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. @VERSION@ $Id: StringParam.java,v 1.3 2005/02/06 23:42:23 lglawrence Exp $

Author:

Lynne Lawrence

See Also:

CmdLineParser

Field Summary

Fields

Modifier and Type	Field and Description
static 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

Constructors

Constructor and Description
StringParam(String tag, String desc) constructor - creates single-valued, optional, parameter accepting a string value of any length
StringParam(String tag, String desc, boolean optional) constructor - creates single-valued, parameter accepting a string value of any length, and either optional or required, as specified.
StringParam(String tag, 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(String tag, 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(String tag, 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(String tag, 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(String tag, String desc, String[] acceptableValues) constructor - creates a single-valued, optional, string parameter whose value must be one of the specified values.
StringParam(String tag, String desc, 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(String tag, String desc, 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(String tag, String desc, 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

Modifier and Type	Method and Description
String	convertValue(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(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 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(String tag,
                   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:

IllegalArgumentException - if tag or desc are invalid.

See Also:

setTag(), setDesc()

StringParam

public StringParam(String tag,
                   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:

IllegalArgumentException - if any of the specified parameters are invalid.

See Also:

setTag(), setDesc()

StringParam

public StringParam(String tag,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setMinValLen(), setMaxValLen()

StringParam

public StringParam(String tag,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setMinValLen(), setMaxValLen(), OPTIONAL, REQUIRED

StringParam

public StringParam(String tag,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setMinValLen(), setMaxValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED

StringParam

public StringParam(String tag,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setMinValLen(), setMaxValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC

StringParam

public StringParam(String tag,
                   String desc,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAcceptableValues(), setMinValLen()

StringParam

public StringParam(String tag,
                   String desc,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAcceptableValues(), setMinValLen(), OPTIONAL, REQUIRED

StringParam

public StringParam(String tag,
                   String desc,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAcceptableValues(), setMinValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED

StringParam

public StringParam(String tag,
                   String desc,
                   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:

IllegalArgumentException - if any parameter is invalid.

See Also:

setTag(), setDesc(), setAcceptableValues(), setMinValLen(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC

Method Detail

convertValue

public String convertValue(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<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:

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:

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:

IllegalArgumentException - if minValLen less than 0, or is greater than maxValLen .

validateValue

public void validateValue(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<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.