uk.ac.starlink.ttools.plottask
Class NamedObjectParameter<T>

java.lang.Object
  extended by uk.ac.starlink.task.Parameter<T>
      extended by uk.ac.starlink.ttools.plottask.NamedObjectParameter<T>
Direct Known Subclasses:
ColorParameter, DashParameter

public abstract class NamedObjectParameter<T>
extends Parameter<T>

Parameter subclass for selecting named options. This resembles ChoiceParameter in that several named choices are available. However, it is also possible to select options which are not in the known option list. For this to work, a pair of methods toString(java.lang.Object) and fromString(java.lang.String) must be implemented as inverses of each other so that a string can be turned into an object. The supplied options do not need to have names which follow this scheme. Note: this class duplicates some of the functionality in other Parameter subclasses. It's here for historical reasons. New code in general ought not to make use of this class.

Since:
14 Aug 2008
Author:
Mark Taylor

Field Summary
 
Fields inherited from class uk.ac.starlink.task.Parameter
BY_NAME
 
Constructor Summary
NamedObjectParameter(String name, Class<T> clazz)
          Constructs a new parameter with no named options.
 
Method Summary
 void addOption(String name, T option)
          Adds an option with an associated name.
abstract  T fromString(String name)
          Translates a string value for this parameter into the object value which it represents.
 String[] getNames()
          Returns the names of all the named options known for this parameter.
 String getOptionList()
          Returns a formatted XML string giving an unordered list of the options for this parameter.
 T[] getOptions()
          Returns the option objects for all the named options known for this parameter.
 String getUsage()
          Returns the usage string for this parameter.
 void setDefaultOption(T option)
          Sets the default value of this parameter as an option value object.
 void setUsage(String usage)
          Sets a usage string for this parameter.
 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.
 String toString(T option)
          Translates a possible option value of this parameter into a string which represents it as a string value.
 
Methods inherited from class uk.ac.starlink.task.Parameter
clearValue, getDescription, getName, getPosition, getPreferExplicit, getPrompt, getStringDefault, getValueClass, isNullPermitted, objectToString, 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

NamedObjectParameter

public NamedObjectParameter(String name,
                            Class<T> clazz)
Constructs a new parameter with no named options.

Parameters:
name - parameter name
Method Detail

addOption

public void addOption(String name,
                      T option)
Adds an option with an associated name. This name does not need to be toString(option).

Parameters:
name - option alias
option - option value object

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

setDefaultOption

public void setDefaultOption(T option)
Sets the default value of this parameter as an option value object. option must be either one of the values added using addOption(java.lang.String, T) or toString(java.lang.Object) must be able to translate it. Or it could be null.

Parameters:
option - new default value as an object

toString

public String toString(T option)
Translates a possible option value of this parameter into a string which represents it as a string value.

Parameters:
option - object value
Returns:
corresponding string

fromString

public abstract T fromString(String name)
Translates a string value for this parameter into the object value which it represents. Must return a suitable object value for this parameter, or throw an unchecked exception.

The implementation must be such that fromString(toString(o)).equals(o).

Parameters:
name - option name
Returns:
corresponding option value

getOptionList

public String getOptionList()
Returns a formatted XML string giving an unordered list of the options for this parameter. Suitable for insertion into a parameter description. Not enclosed in a <p> element.

Returns:
option list XML string

getNames

public String[] getNames()
Returns the names of all the named options known for this parameter.

Returns:
name list

getOptions

public T[] getOptions()
Returns the option objects for all the named options known for this parameter.

Returns:
object list

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

getUsage

public String getUsage()
Description copied from class: Parameter
Returns the usage string for this parameter.

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


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