jcmdline
Class TimeParam

java.lang.Object
  extended byjcmdline.AbstractParameter
      extended byjcmdline.TimeParam
All Implemented Interfaces:
Parameter

public class TimeParam
extends AbstractParameter

A parameter that accepts a time as its value.

The format for the time is "HH:mm:ss:SSS", where the seconds and/or milliseconds portion may be left off by the user, in which case they will be defaulted.

Sample Usage:

     TimeParam startTimeParam = 
         new TimeParam("startTime", 
                       "start time of report", 
                       TimeParam.REQUIRED);
     TimeParam endTimeParam = 
         new TimeParam("endTime", 
                       "end time of report", 
                       TimeParam.REQUIRED);
 
     // Seconds and millis for startTime will both be 0 by default.
     // Set the seconds and millis for the end of the report to be the end 
     // of a minute.
     endTimeParam.setDefaultSeconds(59);
     endTimeParam.setDefaultMilliSeconds(999);
 
     CmdLineHandler cl = new DefaultCmdLineHandler(
         "myreport", "generate current activity report",
         new Parameter[] {}, 
         new Parameter[] { startTimeParam, endTimeParam });
     
     cl.parse();
 
     // Don't need to check isSet() because params are REQUIRED
     Date today = new Date();
     Date stTime = startTimeParam.getDate(today);
     Date enTime = endTimeParam.getDate(today);
     .
     .
  
This will result in a command line that may be executed as:
   myreport "10:12" "23:34"
  
or
   myreport "10:12:34:567" "23:34:34:567"
  

Version:
jcmdline Rel. 1.0.3 $Id: TimeParam.java,v 1.2 2002/12/07 14:22:06 lglawrence Exp $
Author:
Lynne Lawrence
See Also:
DateParam, TimeParam

Field Summary
 
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
TimeParam(java.lang.String tag, java.lang.String desc)
          constructor - creates single-valued, optional, public parameter
TimeParam(java.lang.String tag, java.lang.String desc, boolean optional)
          constructor - creates single-valued, public parameter which will will be either optional or required, as specified.
TimeParam(java.lang.String tag, java.lang.String desc, boolean optional, boolean multiValued)
          constructor - creates a public parameter which will will be either optional or required, and/or multi-valued, as specified.
TimeParam(java.lang.String tag, java.lang.String desc, boolean optional, boolean multiValued, boolean hidden)
          constructor - creates a parameter which will will be either optional or required, single or multi-valued, and hidden or public as specified.
TimeParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues)
          constructor - creates a single-valued, optional, public, number parameter whose value must be one of the specified values.
TimeParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues, boolean optional)
          constructor - creates a single-valued, public, number parameter whose value must be one of the specified values, and which is required or optional, as specified.
TimeParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues, boolean optional, boolean multiValued)
          constructor - creates a public number parameter whose value must be one of the specified values, and which is required or optional and/or multi-valued, as specified.
TimeParam(java.lang.String tag, java.lang.String desc, java.lang.String[] acceptableValues, boolean optional, boolean multiValued, boolean hidden)
          constructor - creates a Parameter, all of whose options are specified.
 
Method Summary
 java.lang.String[] getAcceptableValues()
          Gets the values that are acceptable for this parameter, if a restricted set exists.
 java.util.Date getDate(java.util.Date datePortion)
          Returns a Date object whose date portion is taken from the passed Date object, and whose time portion is taken from the first value set.
 java.util.Date[] getDates(java.util.Date datePortion)
          Returns Date objects whose date portion is taken from the passed Date object, and whose time portion is taken from the first value set.
 int getDefaultMilliSeconds()
          Gets the default millisecond value to use if not specified by the user.
 int getDefaultSeconds()
          Gets the seconds default to use if not specified by the user.
 java.lang.String getFullValue()
          Gets the first value with all time components filled in, from the defaults, if necessary.
 java.lang.String[] getFullValues()
          Gets the values with all time components filled in, from the defaults, if necessary.
 long getMilliValue()
          Gets the number of milliseconds represented by the first value of the parameter.
 long[] getMilliValues()
          Gets the number of milliseconds represented by all values.
 void setAcceptableValues(java.util.Collection vals)
          Sets acceptable values for this Parameter.
 void setAcceptableValues(java.lang.String[] vals)
          Sets acceptable values for this Parameter.
 void setDefaultMilliSeconds(int defaultMilliSeconds)
          Sets the default millisecond value to use if not specified by the user.
 void setDefaultSeconds(int defaultSeconds)
          Sets the seconds default to use if not specified by the user.
 void validateValue(java.lang.String val)
          Verifies that value is valid for this entity - called by add/setValue(s)().
 
Methods inherited from class jcmdline.AbstractParameter
addValue, getDesc, getIgnoreRequired, getOptionLabel, getTag, getValue, getValues, isHidden, isMultiValued, isOptional, isSet, 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
 

Constructor Detail

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc)
constructor - creates single-valued, optional, public parameter

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

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 boolean optional)
constructor - creates single-valued, public parameter which will will be 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()

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 boolean optional,
                 boolean multiValued)
constructor - creates a public parameter which will will be either optional or required, 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
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 of the specified parameters are invalid.
See Also:
setTag(), setDesc(), SINGLE_VALUED, MULTI_VALUED

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 boolean optional,
                 boolean multiValued,
                 boolean hidden)
constructor - creates a parameter which will will be either optional or required, single or multi-valued, and hidden or public 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
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 of the specified parameters are invalid.
See Also:
setTag(), setDesc(), SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 java.lang.String[] acceptableValues)
constructor - creates a single-valued, optional, public, number 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()

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 java.lang.String[] acceptableValues,
                 boolean optional)
constructor - creates a single-valued, public, number parameter whose value must be one of the specified values, and which is required or optional, 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(), OPTIONAL, REQUIRED

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 java.lang.String[] acceptableValues,
                 boolean optional,
                 boolean multiValued)
constructor - creates a public number parameter whose value must be one of the specified values, and which is required or 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(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED

TimeParam

public TimeParam(java.lang.String tag,
                 java.lang.String desc,
                 java.lang.String[] acceptableValues,
                 boolean optional,
                 boolean multiValued,
                 boolean hidden)
constructor - creates a Parameter, all of whose options are 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(), OPTIONAL, REQUIRED, SINGLE_VALUED, MULTI_VALUED, HIDDEN, PUBLIC
Method Detail

validateValue

public void validateValue(java.lang.String val)
                   throws CmdLineException
Verifies that value is valid for this entity - called by add/setValue(s)().

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

getDate

public java.util.Date getDate(java.util.Date datePortion)
Returns a Date object whose date portion is taken from the passed Date object, and whose time portion is taken from the first value set.

Parameters:
datePortion - The date portion of the returned date will match the date portion of this object. Any time portion of this object will be discarded, and the time associated with the initial value of this parameter substituted.
Returns:
See the paramter description.

getDates

public java.util.Date[] getDates(java.util.Date datePortion)
Returns Date objects whose date portion is taken from the passed Date object, and whose time portion is taken from the first value set.

Parameters:
datePortion - The date portion of the returned dates will match the date portion of this object. Any time portion of this object will be discarded, and the time associated with the values of this parameter substituted.
Returns:
See the paramter description.

getMilliValue

public long getMilliValue()
Gets the number of milliseconds represented by the first value of the parameter. This is equal to:
 hours*MILLIS_PER_HOUR + mins*MILLIS_PER_MINUTE + secs*MILLIS_PER_SECOND + ms
 

Returns:
the number of milliseconds represented by the first value of the parameter

getMilliValues

public long[] getMilliValues()
Gets the number of milliseconds represented by all values.

Returns:
the number of milliseconds represented by all values
See Also:
getMilliValue()

getFullValue

public java.lang.String getFullValue()
Gets the first value with all time components filled in, from the defaults, if necessary. This method is guaranteed to return a String in the format "HH:mm:ss:SSS", even if the user did not specify second or millisecond components (unlike getValue() , which returns exactly what the user specified).

Returns:
see description

getFullValues

public java.lang.String[] getFullValues()
Gets the values with all time components filled in, from the defaults, if necessary. This method is guaranteed to return Strings in the format "HH:mm:ss:SSS", even if the user did not specify second or millisecond components (unlike getValues() , which returns exactly what the user specified).

Returns:
see description

setDefaultSeconds

public void setDefaultSeconds(int defaultSeconds)
Sets the seconds default to use if not specified by the user. This will default to 0 if never specified for a TimeParam object.

Parameters:
defaultSeconds - the seconds default to use if not specified by the user
See Also:
getDefaultSeconds()

getDefaultSeconds

public int getDefaultSeconds()
Gets the seconds default to use if not specified by the user. This will default to 0 if never specified for a TimeParam object.

Returns:
the seconds default to use if not specified by the user
See Also:
setDefaultSeconds()

setDefaultMilliSeconds

public void setDefaultMilliSeconds(int defaultMilliSeconds)
Sets the default millisecond value to use if not specified by the user. This will default to 0 if never specified for a TimeParam object.

Parameters:
defaultMilliSeconds - the default millisecond value to use if not specified by the user
See Also:
getDefaultMilliSeconds()

getDefaultMilliSeconds

public int getDefaultMilliSeconds()
Gets the default millisecond value to use if not specified by the user. This will default to 0 if never specified for a TimeParam object.

Returns:
the default millisecond value to use if not specified by the user
See Also:
setDefaultMilliSeconds()

setAcceptableValues

public void setAcceptableValues(java.util.Collection vals)
Sets acceptable values for this Parameter.

Specified by:
setAcceptableValues in interface Parameter
Overrides:
setAcceptableValues in class AbstractParameter
Parameters:
vals - A Collection of Strings representing the acceptable times. If the seconds and/or milliseconds portion of the time is left off, the default values will be used when user input is compared.

setAcceptableValues

public void setAcceptableValues(java.lang.String[] vals)
Sets acceptable values for this Parameter.

Specified by:
setAcceptableValues in interface Parameter
Overrides:
setAcceptableValues in class AbstractParameter
Parameters:
vals - An array of Strings representing the acceptable times. If the seconds and/or milliseconds portion of the time is left off, the default values will be used when user input is compared.
See Also:
AbstractParameter.getAcceptableValues()

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
Overrides:
getAcceptableValues in class AbstractParameter
Returns:
a set of acceptable values for the Parameter, or null if there is none.
See Also:
setAcceptableValues()