uk.ac.starlink.task
Class ChoiceParameter<T>

java.lang.Object
  extended by uk.ac.starlink.task.Parameter<T>
      extended by uk.ac.starlink.task.ChoiceParameter<T>
Direct Known Subclasses:
DataStoreParameter, FindModeParameter, JoinFixActionParameter, JoinTypeParameter, LayerTypeParameter, PaintModeParameter, ProgressIndicatorParameter, StyleParameter

public class ChoiceParameter<T>
extends Parameter<T>

Parameter whose legal value must be one of a disjunction of given values. Matching is case-insensitive against the stringified value of the option.

Since:
15 Aug 2005
Author:
Mark Taylor

Field Summary
 
Fields inherited from class uk.ac.starlink.task.Parameter
BY_NAME
 
Constructor Summary
ChoiceParameter(String name, Class<T> clazz)
          Constructs a choice parameter with no initially set options.
ChoiceParameter(String name, Class<T> clazz, T[] options)
          Constructor.
ChoiceParameter(String name, T[] options)
          Constructs a choice parameter with an initial option set.
 
Method Summary
 void addOption(T option)
          Adds an option value to this parameter.
 void addOption(T option, String name)
          Adds an option value to this parameter with a given name.
 void clearOptions()
          Clears the list of known options.
 String getName(T option)
          Converts an option value object to a string which is used to identify it as a string value of this parameter.
 T getOption(String name)
          Returns the option value associated with a given string by this parameter.
 String[] getOptionNames()
          Returns an array of the string values of options accepted by this parameter.
 T[] getOptions()
          Returns an array of the option objects which may form the values of this parameter.
 Collection<T> getOptionValueList()
          Returns a collection of the option objects which may form the values of this parameter.
 String getUsage()
          Returns a usage message.
 String objectToString(Environment env, T objVal)
          Takes a typed value of this parameter and formats it as a string which may be used for presentation to the user.
 void setDefaultOption(T option)
          Sets the default value for this parameter to one of the previously added options.
 void setUsage(String usage)
          Sets a usage string for this parameter.
 String stringifyOption(T option)
          Determines how an option will be represented as a string value of this parameter if no name has explicitly been supplied.
 T stringToObject(Environment env, String sval)
          Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter.
 
Methods inherited from class uk.ac.starlink.task.Parameter
clearValue, getDescription, getName, getPosition, getPreferExplicit, getPrompt, getStringDefault, getValueClass, isNullPermitted, objectValue, setDescription, setDescription, setName, setNullPermitted, setPosition, setPreferExplicit, setPrompt, setStringDefault, setValue, setValueFromObject, setValueFromString, stringValue, toArray, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ChoiceParameter

public ChoiceParameter(String name,
                       Class<T> clazz,
                       T[] options)
Constructor.

Parameters:
name - parameter name
clazz - type for values of this parameter
options - initial array of legal values of this parameter

ChoiceParameter

public ChoiceParameter(String name,
                       Class<T> clazz)
Constructs a choice parameter with no initially set options.

Parameters:
name - parameter name
clazz - type for values of this parameter

ChoiceParameter

public ChoiceParameter(String name,
                       T[] options)
Constructs a choice parameter with an initial option set. The data type is taken from the supplied array type.

Parameters:
name - parameter name
options - initial array of legal values of this parameter
Method Detail

stringToObject

public T stringToObject(Environment env,
                        String sval)
                 throws TaskException
Description copied from class: Parameter
Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter. This method also performs validation, so if the string value is unacceptable in any way, a ParameterValueException should be thrown.

It is an error to supply a null or empty string value.

If this method fails (throws a ParameterValueException) and if allowClassnameValue is set, then a subsequent attempt will be made to interpret the stringVal as the classname of a suitable class with a no-arg constructor.

Specified by:
stringToObject in class Parameter<T>
Parameters:
env - execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the result
sval - non-null, non-empty string value
Returns:
typed value
Throws:
TaskException

objectToString

public String objectToString(Environment env,
                             T objVal)
Description copied from class: Parameter
Takes a typed value of this parameter and formats it as a string which may be used for presentation to the user. Ideally, round-tripping between this method and stringToObject should be possible, but that is not in general required/guaranteed.

The default implementation uses the value's toString method, but subclasses can override this for smarter behaviour.

Overrides:
objectToString in class Parameter<T>
Parameters:
env - execution environment
objVal - typed parameter value
Returns:
string value for presentation

addOption

public void addOption(T option,
                      String name)
Adds an option value to this parameter with a given name. The name is the parameter value string used to identify this option.

Parameters:
option - option object
name - label for option

addOption

public void addOption(T option)
Adds an option value to this parameter. The option's name will be determined by this object's stringifyOption(T) method.

Parameters:
option - option object

clearOptions

public void clearOptions()
Clears the list of known options.


getUsage

public String getUsage()
Returns a usage message. Unless it has been overriden by an earlier call to setUsage(java.lang.String), this will return a usage message based on the list of known options.

Overrides:
getUsage in class Parameter<T>
Returns:
usage message
See Also:
Parameter.setUsage(java.lang.String)

setUsage

public void setUsage(String usage)
Description copied from class: Parameter
Sets a usage string for this parameter. This should be terse (in particular no newline characters) and conform to the following rules: The Parameter class uses the string "<value>" as the default usage string.

Overrides:
setUsage in class Parameter<T>
Parameters:
usage - usage string

setDefaultOption

public void setDefaultOption(T option)
Sets the default value for this parameter to one of the previously added options.

Parameters:
option - default option

getOptionNames

public String[] getOptionNames()
Returns an array of the string values of options accepted by this parameter.

Returns:
permitted options, stringified

getOptions

public T[] getOptions()
Returns an array of the option objects which may form the values of this parameter.

Returns:
permitted options

getOptionValueList

public Collection<T> getOptionValueList()
Returns a collection of the option objects which may form the values of this parameter.

Returns:
permitted options

getName

public String getName(T option)
Converts an option value object to a string which is used to identify it as a string value of this parameter.

Parameters:
option - option value
Returns:
string representation

stringifyOption

public String stringifyOption(T option)
Determines how an option will be represented as a string value of this parameter if no name has explicitly been supplied. The default implementation is String.valueOf(option), but this may be overrridden.

Parameters:
option - option value
Returns:
string representation of option

getOption

public T getOption(String name)
Returns the option value associated with a given string by this parameter. Null is returned if none of the options added so far has a name as supplied. Name matching is case-insensitive.

Parameters:
name - name of option which has been added
Returns:
correspondig option object


Copyright © 2015 Central Laboratory of the Research Councils. All Rights Reserved.