uk.ac.starlink.ttools.plottask

Class NamedObjectParameter<T>

java.lang.Object

uk.ac.starlink.task.Parameter<T>

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

Constructors

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

Method Summary

Modifier and Type	Method and Description
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 name is not included in the message
• placeholders are enclosed in angle brackets (<>)
• literals are not enclosed in angle brackets
• a disjunction is represented using the "|" character

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)