de.lmu.ifi.dbs.elki.utilities.optionhandling.parameters
Class Parameter<S,T extends S>

java.lang.Object
  extended by de.lmu.ifi.dbs.elki.utilities.optionhandling.parameters.Parameter<S,T>
Type Parameters:
T - the type of a possible value (i.e., the type of the option)
S - the supertype for constraints
Direct Known Subclasses:
ClassParameter, DistanceParameter, EnumParameter, FileParameter, Flag, ListParameter, NumberParameter, PatternParameter, StringParameter

public abstract class Parameter<S,T extends S>
extends Object

Abstract class for specifying a parameter. A parameter is defined as an option having a specific value. See the de.lmu.ifi.dbs.elki.utilities.optionhandling package for documentation!


Field Summary
protected  List<ParameterConstraint<S>> constraints
          Holds parameter constraints for this parameter.
protected  T defaultValue
          The default value of the parameter (may be null).
private  boolean defaultValueTaken
          Specifies if the default value of this parameter was taken as parameter value.
protected  T givenValue
          The value last passed to this option.
protected  boolean optionalParameter
          Specifies if this parameter is an optional parameter.
protected  OptionID optionid
          The option name.
protected  String shortDescription
          The short description of the option.
private  T value
          The value of this option.
 
Constructor Summary
Parameter(OptionID optionID)
          Constructs a parameter with the given optionID.
Parameter(OptionID optionID, boolean optional)
          Constructs a parameter with the given optionID and optional flag.
Parameter(OptionID optionID, List<ParameterConstraint<S>> constraints)
          Constructs a parameter with the given optionID, and constraints.
Parameter(OptionID optionID, List<ParameterConstraint<S>> constraints, boolean optional)
          Constructs a parameter with the given optionID, constraints, and optional flag.
Parameter(OptionID optionID, List<ParameterConstraint<S>> constraints, T defaultValue)
          Constructs a parameter with the given optionID, constraints, and default value.
Parameter(OptionID optionID, ParameterConstraint<S> constraint)
          Constructs a parameter with the given optionID, and constraint.
Parameter(OptionID optionID, ParameterConstraint<S> constraint, boolean optional)
          Constructs a parameter with the given optionID, constraint, and optional flag.
Parameter(OptionID optionID, ParameterConstraint<S> constraint, T defaultValue)
          Constructs a parameter with the given optionID, constraint, and default value.
Parameter(OptionID optionID, T defaultValue)
          Constructs a parameter with the given optionID and default value.
 
Method Summary
 void addConstraint(ParameterConstraint<S> constraint)
          Add an additional constraint.
 T getDefaultValue()
          Returns the default value of the parameter.
 String getDefaultValueAsString()
          Get the default value as string.
 String getFullDescription()
          Returns the extended description of the option which includes the option's type, the short description and the default value (if specified).
 Object getGivenValue()
          Get the last given value.
 String getName()
          Returns the name of the option.
 OptionID getOptionID()
          Return the OptionID of this option.
 String getShortDescription()
          Returns the short description of the option.
abstract  String getSyntax()
          Returns a string representation of the parameter's type (e.g. an IntParameter should return <int>).
 T getValue()
          Returns the value of the option.
abstract  String getValueAsString()
          Get the value as string.
 String getValuesDescription()
          Return a string explaining valid values.
 boolean hasDefaultValue()
          Checks if this parameter has a default value.
 boolean hasValuesDescription()
          Whether this class has a list of default values.
 boolean isDefined()
          Returns true if the value of the option is defined, false otherwise.
 boolean isOptional()
          Checks if this parameter is an optional parameter.
 boolean isValid(Object obj)
          Checks if the given argument is valid for this option.
private static
<S> List<ParameterConstraint<S>>
makeConstraintsVector(ParameterConstraint<S> constraint)
          Wrap a single constraint into a vector of constraints.
protected abstract  T parseValue(Object obj)
          Parse a given value into the destination type.
 void setDefaultValue(T defaultValue)
          Sets the default value of this parameter.
 void setOptional(boolean opt)
          Specifies if this parameter is an optional parameter.
 void setShortDescription(String description)
          Sets the short description of the option.
 void setValue(Object obj)
          Sets the value of the option.
protected  void setValueInternal(T val)
          Internal setter for the value.
 boolean tookDefaultValue()
          Checks if the default value of this parameter was taken as the actual parameter value.
 boolean tryDefaultValue()
          Handle default values for a parameter.
 void useDefaultValue()
          Sets the default value of this parameter as the actual value of this parameter.
protected  boolean validate(T obj)
          Validate a value after parsing (e.g. do constrain checks!)
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultValue

protected T extends S defaultValue
The default value of the parameter (may be null).


defaultValueTaken

private boolean defaultValueTaken
Specifies if the default value of this parameter was taken as parameter value.


optionalParameter

protected boolean optionalParameter
Specifies if this parameter is an optional parameter.


constraints

protected final List<ParameterConstraint<S>> constraints
Holds parameter constraints for this parameter.


optionid

protected final OptionID optionid
The option name.


shortDescription

protected String shortDescription
The short description of the option. An extended description is provided by the method getFullDescription()


givenValue

protected T extends S givenValue
The value last passed to this option.


value

private T extends S value
The value of this option.

Constructor Detail

Parameter

public Parameter(OptionID optionID,
                 List<ParameterConstraint<S>> constraints,
                 T defaultValue)
Constructs a parameter with the given optionID, constraints, and default value.

Parameters:
optionID - the unique id of this parameter
constraints - the constraints of this parameter, may be empty if there are no constraints
defaultValue - the default value of this parameter (may be null)

Parameter

public Parameter(OptionID optionID,
                 List<ParameterConstraint<S>> constraints,
                 boolean optional)
Constructs a parameter with the given optionID, constraints, and optional flag.

Parameters:
optionID - the unique id of this parameter
constraints - the constraints of this parameter, may be empty if there are no constraints
optional - specifies if this parameter is an optional parameter

Parameter

public Parameter(OptionID optionID,
                 List<ParameterConstraint<S>> constraints)
Constructs a parameter with the given optionID, and constraints.

Parameters:
optionID - the unique id of this parameter
constraints - the constraints of this parameter, may be empty if there are no constraints

Parameter

public Parameter(OptionID optionID,
                 ParameterConstraint<S> constraint,
                 T defaultValue)
Constructs a parameter with the given optionID, constraint, and default value.

Parameters:
optionID - the unique id of this parameter
constraint - the constraint of this parameter
defaultValue - the default value of this parameter (may be null)

Parameter

public Parameter(OptionID optionID,
                 ParameterConstraint<S> constraint,
                 boolean optional)
Constructs a parameter with the given optionID, constraint, and optional flag.

Parameters:
optionID - the unique id of this parameter
constraint - the constraint of this parameter
optional - specifies if this parameter is an optional parameter

Parameter

public Parameter(OptionID optionID,
                 ParameterConstraint<S> constraint)
Constructs a parameter with the given optionID, and constraint.

Parameters:
optionID - the unique id of this parameter
constraint - the constraint of this parameter

Parameter

public Parameter(OptionID optionID,
                 T defaultValue)
Constructs a parameter with the given optionID and default value.

Parameters:
optionID - the unique id of the option
defaultValue - default value.

Parameter

public Parameter(OptionID optionID,
                 boolean optional)
Constructs a parameter with the given optionID and optional flag.

Parameters:
optionID - the unique id of the option
optional - optional flag

Parameter

public Parameter(OptionID optionID)
Constructs a parameter with the given optionID.

Parameters:
optionID - the unique id of the option
Method Detail

makeConstraintsVector

private static <S> List<ParameterConstraint<S>> makeConstraintsVector(ParameterConstraint<S> constraint)
Wrap a single constraint into a vector of constraints.

Type Parameters:
S - Type
Parameters:
constraint - Constraint, may be null
Returns:
Vector containing the constraint (if not null)

setDefaultValue

public void setDefaultValue(T defaultValue)
Sets the default value of this parameter.

Parameters:
defaultValue - default value of this parameter

hasDefaultValue

public boolean hasDefaultValue()
Checks if this parameter has a default value.

Returns:
true, if this parameter has a default value, false otherwise

useDefaultValue

public void useDefaultValue()
Sets the default value of this parameter as the actual value of this parameter.


tryDefaultValue

public boolean tryDefaultValue()
                        throws UnspecifiedParameterException
Handle default values for a parameter.

Returns:
Return code: true if it has a default value, false if it is optional without a default value. Exception if it is a required parameter!
Throws:
UnspecifiedParameterException - If the parameter requires a value

setOptional

public void setOptional(boolean opt)
Specifies if this parameter is an optional parameter.

Parameters:
opt - true if this parameter is optional, false otherwise

isOptional

public boolean isOptional()
Checks if this parameter is an optional parameter.

Returns:
true if this parameter is optional, false otherwise

tookDefaultValue

public boolean tookDefaultValue()
Checks if the default value of this parameter was taken as the actual parameter value.

Returns:
true, if the default value was taken as actual parameter value, false otherwise

isDefined

public boolean isDefined()
Returns true if the value of the option is defined, false otherwise.

Returns:
true if the value of the option is defined, false otherwise.

getDefaultValue

public T getDefaultValue()
Returns the default value of the parameter.

If the parameter has no default value, the method returns null.

Returns:
the default value of the parameter, null if the parameter has no default value.

hasValuesDescription

public boolean hasValuesDescription()
Whether this class has a list of default values.

Returns:
whether the class has a description of valid values.

getValuesDescription

public String getValuesDescription()
Return a string explaining valid values.

Returns:
String explaining valid values (e.g. a class list)

getFullDescription

public String getFullDescription()
Returns the extended description of the option which includes the option's type, the short description and the default value (if specified).

Returns:
the option's description.

validate

protected boolean validate(T obj)
                    throws ParameterException
Validate a value after parsing (e.g. do constrain checks!)

Parameters:
obj - Object to validate
Returns:
true iff the object is valid for this parameter.
Throws:
ParameterException - when the object is not valid.

getOptionID

public OptionID getOptionID()
Return the OptionID of this option.

Returns:
Option ID

getName

public String getName()
Returns the name of the option.

Returns:
the option's name.

getShortDescription

public String getShortDescription()
Returns the short description of the option.

Returns:
the option's short description.

setShortDescription

public void setShortDescription(String description)
Sets the short description of the option.

Parameters:
description - the short description to be set

setValue

public void setValue(Object obj)
              throws ParameterException
Sets the value of the option.

Parameters:
obj - the option's value to be set
Throws:
ParameterException - if the given value is not a valid value for this option.

setValueInternal

protected final void setValueInternal(T val)
Internal setter for the value.

Parameters:
val - Value

getValue

public final T getValue()
Returns the value of the option. You should use either {Parameterization#grab} or isDefined() to test if getValue() will return a well-defined value.

Returns:
the option's value.

getGivenValue

public Object getGivenValue()
Get the last given value. May return null

Returns:
Given value

isValid

public final boolean isValid(Object obj)
                      throws ParameterException
Checks if the given argument is valid for this option.

Parameters:
obj - option value to be checked
Returns:
true, if the given value is valid for this option
Throws:
ParameterException - if the given value is not a valid value for this option.

getSyntax

public abstract String getSyntax()
Returns a string representation of the parameter's type (e.g. an IntParameter should return <int>).

Returns:
a string representation of the parameter's type

parseValue

protected abstract T parseValue(Object obj)
                                   throws ParameterException
Parse a given value into the destination type.

Parameters:
obj - Object to parse (may be a string representation!)
Returns:
Parsed object
Throws:
ParameterException - when the object cannot be parsed.

getValueAsString

public abstract String getValueAsString()
Get the value as string. May return null

Returns:
Value as string

getDefaultValueAsString

public String getDefaultValueAsString()
Get the default value as string.

Returns:
default value

addConstraint

public void addConstraint(ParameterConstraint<S> constraint)
Add an additional constraint.

Parameters:
constraint - Constraint to add.

Release 0.4.0 (2011-09-20_1324)