Parameter (Starlink-UK API)

java.lang.Object
- uk.ac.starlink.task.Parameter<T>

Direct Known Subclasses:

AbstractChoiceParameter, AbstractInputTableParameter, BooleanParameter, CompositorParameter, ConeErrorPolicyParameter, ConfigParameter, ConnectionParameter, DoubleArrayParameter, DoubleParameter, FilterParameter, InputStreamParameter, IntegerParameter, LongParameter, Match1TypeParameter, MatchEngineParameter, NamedObjectParameter, ObjectFactoryParameter, OutputReporterParameter, OutputStreamParameter, OutputTableParameter, PaddingParameter, StringMultiParameter, StringParameter, TableFactoryParameter, TilingParameter, URLParameter, WordsParameter, XmlEncodingParameter
```
public abstract class Parameter<T>
extends Object
```
A Parameter describes the function of one of a task's parameters. An instance of the class encapsulates a parameter's name, value type, prompt string, default value, position on the command line, and so on. It can also validate, hold and clear the value of the parameter. The parameter value is acquired from an associated Environment in either String or typed form, and the Parameter object configures its value from that.
This class must be subclassed according to the type of values it obtains. Such concrete subclasses must implement the stringToObject(uk.ac.starlink.task.Environment, java.lang.String) method to perform mapping from an environment-supplied string value to a typed parameter value, including validation.

Author:

Mark Taylor (Starlink)

See Also:

Task, Environment

Field Summary

Fields
Modifier and Type Field and Description

static Comparator<Parameter<?>> BY_NAME
Compares parameters alphabetically by parameter name.

Fields
Modifier and Type	Field and Description
`static Comparator<Parameter<?>>`	`BY_NAME` Compares parameters alphabetically by parameter name.

Constructor Summary

Constructors
Constructor and Description

Parameter(String name, Class<T> clazz, boolean allowClassnameValue)
Constructs a parameter with a given name.

Constructors
Constructor and Description
`Parameter(String name, Class<T> clazz, boolean allowClassnameValue)` Constructs a parameter with a given name.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clearValue(Environment env)` Clears the value of this parameter.
`String`	`getDescription()` Returns the textual description for this parameter.
`String`	`getName()` Returns the name of this parameter.
`int`	`getPosition()` Gets the position of this parameter in a parameter list; the first parameter is 1.
`boolean`	`getPreferExplicit()` Determine whether an explict value is generally preferred to the default value for this parameter.
`String`	`getPrompt()` Gets the prompt string for this parameter, as displayed to the user when the value of the parameter is requested.
`String`	`getStringDefault()` Gets the default string value for this parameter.
`String`	`getUsage()` Returns the usage string for this parameter.
`Class<T>`	`getValueClass()` Returns the class of the typed values this parameter takes.
`boolean`	`isNullPermitted()` Determine whether it is legal for this parameter's value to be blank.
`String`	`objectToString(Environment env, T objectVal)` Takes a typed value of this parameter and formats it as a string which may be used for presentation to the user.
`T`	`objectValue(Environment env)` Gets the value of this parameter as a typed object.
`void`	`setDescription(String description)` Sets the textual description for this parameter.
`void`	`setDescription(String[] descLines)` Convenience method to set the description for this parameter by the result of joining an array of lines together.
`void`	`setName(String name)` Sets the name of this parameter.
`void`	`setNullPermitted(boolean permitted)` Set whether it is legal for this parameter's value to be blank.
`void`	`setPosition(int pos)` Sets the position of this parameter in a parameter list; the first parameter is 1.
`void`	`setPreferExplicit(boolean prefer)` Set whether an explicit value is generally to be solicited from the user rather than taking the default.
`void`	`setPrompt(String prompt)` Sets the prompt string for this parameter, as displayed to the user when the value of the parameter is requested.
`void`	`setStringDefault(String stringDflt)` Sets the default string value for this parameter.
`void`	`setUsage(String usage)` Sets a usage string for this parameter.
`protected void`	`setValue(String stringValue, T objectValue)` Sets the value of this parameter without any additional validation.
`void`	`setValueFromObject(Environment env, T objectValue)` Sets the value of this parameter directly from a typed object.
`void`	`setValueFromString(Environment env, String stringval)` Sets the value of this parameter from a String.
`abstract T`	`stringToObject(Environment env, String stringVal)` Takes a non-blank string, as supplied by the execution environment, and turns it into a typed value for this parameter.
`String`	`stringValue(Environment env)` Gets the value of this parameter as a String.
`T[]`	`toArray(Collection<T> collection)` Utility function to convert a list to an array, where the elements are of the value class of this parameter.
`String`	`toString()` Returns the name of this parameter.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - BY_NAME
```
public static final Comparator<Parameter<?>> BY_NAME
```
    Compares parameters alphabetically by parameter name.
- Constructor Detail
  - Parameter
```
public Parameter(String name,
                 Class<T> clazz,
                 boolean allowClassnameValue)
```
    Constructs a parameter with a given name. This name should be unique within a given Task.
    If the allowClassnameValue flag is set, then in addition to the options provided by stringToObject, any supplied string value equal to the classname of an available class matching this parameter's value type which has a no-arg constructor will cause a newly constructed instance of that class to be used as a value.
    
    Parameters:
    
    name - the identifying name of this parameter
    
    clazz - the class of this parameter's typed values
    
    allowClassnameValue - whether suitable classnames may be supplied as string values
- Method Detail
  - stringToObject
```
public abstract T stringToObject(Environment env,
                                 String stringVal)
                          throws TaskException
```
    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.
    
    Parameters:
    
    env - execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the result
    
    stringVal - non-null, non-empty string value
    
    Returns:
    
    typed value
    
    Throws:
    
    TaskException
  - objectToString
```
public String objectToString(Environment env,
                             T objectVal)
                      throws TaskException
```
    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.
    
    Parameters:
    
    env - execution environment
    
    objectVal - typed parameter value
    
    Returns:
    
    string value for presentation
    
    Throws:
    
    TaskException
  - setValueFromString
```
public void setValueFromString(Environment env,
                               String stringval)
                        throws TaskException
```
    Sets the value of this parameter from a String. This method is called by the Environment to configure the value of this parameter.
    A null or empty string is intercepted by this method and translated to a null object value or triggers a ParameterValueException according to the value of isNullPermitted().
    
    Parameters:
    
    env - execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the result
    
    stringval - string representation of value
    
    Throws:
    
    TaskException
  - setValueFromObject
```
public void setValueFromObject(Environment env,
                               T objectValue)
                        throws TaskException
```
    Sets the value of this parameter directly from a typed object. In this case the reported string value is obtained by calling objectToString.
    
    Parameters:
    
    env - execution environment; in most cases this is not required but for some purposes environment-specific characteristics may influence the result
    
    objectValue - typed value
    
    Throws:
    
    TaskException
  - stringValue
```
public final String stringValue(Environment env)
                         throws TaskException
```
    Gets the value of this parameter as a String. The value is lazily acquired by the supplied environment object.
    The returned value may be null only if the isNullPermitted() method returns true.
    
    Parameters:
    
    env - execution environment from which value is obtained
    
    Returns:
    
    the value of this parameter as a string, or null
    
    Throws:
    
    AbortException - if during the course of trying to obtain a value the Environment determines that the task should not continue.
    
    TaskException
  - objectValue
```
public final T objectValue(Environment env)
                    throws TaskException
```
    Gets the value of this parameter as a typed object. The value is actually acquired by the supplied environment object.
    The returned value will generally be null if the string value that generated it is null or empty. That is only possible if the isNullPermitted() method returns true.
    
    Parameters:
    
    env - execution environment from which value is obtained
    
    Returns:
    
    the value of this parameter as a string, or null
    
    Throws:
    
    AbortException - if during the course of trying to obtain a value the Environment determines that the task should not continue.
    
    TaskException
  - clearValue
```
public void clearValue(Environment env)
```
    Clears the value of this parameter. Subsequent retrievals of the parameter value will trigger a request to the environment for a new value.
    
    Parameters:
    
    env - execution environment within which value will be cleared
  - setValue
```
protected void setValue(String stringValue,
                        T objectValue)
```
    Sets the value of this parameter without any additional validation. This is invoked by setValueFromString and setValueFromObject, and should not normally be invoked directly.
    
    Parameters:
    
    stringValue - string representation of value
    
    objectValue - typed value
  - getValueClass
```
public Class<T> getValueClass()
```
    Returns the class of the typed values this parameter takes.
    
    Returns:
    
    the class of this parameter's typed values
  - getName
```
public String getName()
```
    Returns the name of this parameter.
    
    Returns:
    
    name the identifying name of this parameter
  - setName
```
public void setName(String name)
```
    Sets the name of this parameter.
    
    Parameters:
    
    name - identifying name of this parameter
  - getPrompt
```
public String getPrompt()
```
    Gets the prompt string for this parameter, as displayed to the user when the value of the parameter is requested. Should be short (<40 characters?).
    
    Returns:
    
    prompt string
  - setPrompt
```
public void setPrompt(String prompt)
```
    Sets the prompt string for this parameter, as displayed to the user when the value of the parameter is requested. Should be short (<40 characters?).
    
    Parameters:
    
    prompt - the prompt string
  - getDescription
```
public String getDescription()
```
    Returns the textual description for this parameter.
    
    Returns:
    
    description, if known
  - setDescription
```
public void setDescription(String description)
```
    Sets the textual description for this parameter.
    
    Parameters:
    
    description - description
  - setDescription
```
public void setDescription(String[] descLines)
```
    Convenience method to set the description for this parameter by the result of joining an array of lines together.
    
    Parameters:
    
    descLines - lines of textual description
    
    See Also:
    
    setDescription(java.lang.String)
  - setUsage
```
public void setUsage(String usage)
```
    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.
    Parameters:
    
    usage - usage string
  - getUsage
```
public String getUsage()
```
    Returns the usage string for this parameter.
    
    Returns:
    
    usage string
    
    See Also:
    
    setUsage(java.lang.String)
  - setNullPermitted
```
public void setNullPermitted(boolean permitted)
```
    Set whether it is legal for this parameter's value to be blank. By default it is not. Note that null and blank string values are treated the same as each other, and are translated to null object values.
    
    Parameters:
    
    permitted - whether null values are to be permitted for this parameter
  - isNullPermitted
```
public boolean isNullPermitted()
```
    Determine whether it is legal for this parameter's value to be blank. By default it is not.
    
    Returns:
    
    true if null values are permitted for this parameter
  - getPreferExplicit
```
public boolean getPreferExplicit()
```
    Determine whether an explict value is generally preferred to the default value for this parameter.
    
    Returns:
    
    true if a default value should generally be avoided
  - setPreferExplicit
```
public void setPreferExplicit(boolean prefer)
```
    Set whether an explicit value is generally to be solicited from the user rather than taking the default.
    
    Parameters:
    
    prefer - true if you would like to encourage an explicit value to be set for this parameter
  - getStringDefault
```
public String getStringDefault()
```
    Gets the default string value for this parameter.
    
    Returns:
    
    the default string value
  - setStringDefault
```
public void setStringDefault(String stringDflt)
```
    Sets the default string value for this parameter. Concrete subclasses may additionally supply type-specific default value setter methods, but those ought to operate by invoking this method.
    
    Parameters:
    
    stringDflt - the default string value
  - getPosition
```
public int getPosition()
```
    Gets the position of this parameter in a parameter list; the first parameter is 1. If the position is 0, the value can only be set by name.
    
    Returns:
    
    parameter position
  - setPosition
```
public void setPosition(int pos)
```
    Sets the position of this parameter in a parameter list; the first parameter is 1. If the position is 0, the value can only be set by name.
    
    Parameters:
    
    pos - parameter position
  - toArray
```
public T[] toArray(Collection<T> collection)
```
    Utility function to convert a list to an array, where the elements are of the value class of this parameter.
    
    Parameters:
    
    collection - typed collection
    
    Returns:
    
    typed array with same contents
  - toString
```
public String toString()
```
    Returns the name of this parameter.
    
    Overrides:
    
    toString in class Object
    
    Returns:
    
    string representation

Class Parameter<T>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BY_NAME

Constructor Detail

Parameter

Method Detail

stringToObject

objectToString

setValueFromString

setValueFromObject

stringValue

objectValue

clearValue

setValue

getValueClass

getName

setName

getPrompt

setPrompt

getDescription

setDescription

setDescription

setUsage

getUsage

setNullPermitted

isNullPermitted

getPreferExplicit

setPreferExplicit

getStringDefault

setStringDefault

getPosition

setPosition

toArray

toString