de.lmu.ifi.dbs.elki.utilities.optionhandling.parameters

Class Parameter<S,T extends S>

java.lang.Object

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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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.