de.jstacs.parameters
Class Parameter

java.lang.Object
  extended by de.jstacs.parameters.Parameter
All Implemented Interfaces:
Storable, Cloneable
Direct Known Subclasses:
CollectionParameter, FileParameter, ParameterSetContainer, RangeParameter, SimpleParameter

public abstract class Parameter
extends Object
implements Storable, Cloneable

Abstract class for a parameter that shall be used as the parameter of some method, constructor, etc. This class provides annotation of the parameter, e.g. a name and a comment, the data type, and additional properties for non-atomic parameters. The intention of the Parameter classes is to link this annotation directly to the parameter values, which could not be achieved by primitive data types.
Parameters should always be embedded into a ParameterSet and then passed to the respective method.

Author:
Jan Grau
See Also:
ParameterSet

Field Summary
protected  ParameterSet neededReference
          In cases, when the validity of some ParameterSet depends on the value of this Parameter, this variable holds a reference to that ParameterSet
protected  Long neededReferenceId
          In addition to the reference, the id of the ParameterSet is saved, which assists reconstruction from XML.
protected  ParameterSet parent
          If this Parameter is enclosed in a ParameterSet, this variable holds a reference to that ParameterSet.
 
Constructor Summary
Parameter()
          Creates a new Parameter and generates the internal id.
 
Method Summary
abstract  boolean checkValue(Object value)
          Checks the value for correctness, e.g. for numerical parameters this might be checking if the value is within specified bounds
 Parameter clone()
           
protected  void fromXML(StringBuffer source)
          Parses a Parameter from an XML-representation as returned by toXML().
abstract  String getComment()
          Returns a comment on this parameter that tells something about useful values, domains, usage of this parameter, etc.
abstract  DataType getDatatype()
          Returns the data type of the parameter
abstract  String getErrorMessage()
          If a value could not be set successfully this method returns the corresponding error message.
 long getId()
          Returns the id of this Parameter.
abstract  String getName()
          Returns the name of the parameter
 ParameterSet getNeededReference()
          Returns a reference to a ParameterSet whose ParameterSet.hasDefaultOrIsSet() method depends on the value of this Parameter.
 Long getNeededReferenceId()
          Returns the id of the ParameterSet that would be returned by getNeededReference().
 ParameterSet getParent()
          Returns a reference to the ParameterSet enclosing this Parameter.
abstract  Object getValue()
          Returns the current value of this Parameter
abstract  boolean hasDefaultOrIsSet()
          Returns true if the parameter either has a default value or the value was set by the user.
abstract  boolean isAtomic()
          Returns true if the parameter is of an atomic data type
abstract  boolean isRequired()
          Returns true if the parameter is required, false otherwise
abstract  boolean isSet()
          Returns true if the parameter was set by the user.
abstract  void reset()
          Resets the parameter and its contents to the default values or null if not defaults are given.
abstract  void setDefault(Object defaultValue)
          Sets the default value of the parameter to defaultValue
 void setNeededReference(ParameterSet reference)
          Sets an internal reference to a ParameterSet whose validity depends on the value of this Parameter.
 void setParent(ParameterSet parent)
          Sets the reference of the enclosing ParameterSet of this Parameter to parent.
abstract  void setValue(Object value)
          Sets the value of this parameter to value.
abstract  void simplify()
          Simplifies the Parameter and its contents to the relevant information.
 StringBuffer toXML()
          This method returns an XML-representation of an instance of the implementing class.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

neededReference

protected ParameterSet neededReference
In cases, when the validity of some ParameterSet depends on the value of this Parameter, this variable holds a reference to that ParameterSet


neededReferenceId

protected Long neededReferenceId
In addition to the reference, the id of the ParameterSet is saved, which assists reconstruction from XML.

See Also:
neededReference

parent

protected ParameterSet parent
If this Parameter is enclosed in a ParameterSet, this variable holds a reference to that ParameterSet.

Constructor Detail

Parameter

public Parameter()
Creates a new Parameter and generates the internal id.

Method Detail

getId

public long getId()
Returns the id of this Parameter.

Returns:
the id

getName

public abstract String getName()
Returns the name of the parameter

Returns:
the name

getDatatype

public abstract DataType getDatatype()
Returns the data type of the parameter

Returns:
the data type

getComment

public abstract String getComment()
Returns a comment on this parameter that tells something about useful values, domains, usage of this parameter, etc.

Returns:
the comment

isRequired

public abstract boolean isRequired()
Returns true if the parameter is required, false otherwise

Returns:
if the parameter is required

checkValue

public abstract boolean checkValue(Object value)
Checks the value for correctness, e.g. for numerical parameters this might be checking if the value is within specified bounds

Parameters:
value - the value to be checked
Returns:
if the value is valid

setValue

public abstract void setValue(Object value)
                       throws SimpleParameter.IllegalValueException
Sets the value of this parameter to value.

Parameters:
value - the new value
Throws:
SimpleParameter.IllegalValueException - if the specified value is not valid for this Parameter an IllegalValueException is thrown

getValue

public abstract Object getValue()
Returns the current value of this Parameter

Returns:
the current value

hasDefaultOrIsSet

public abstract boolean hasDefaultOrIsSet()
Returns true if the parameter either has a default value or the value was set by the user.

Returns:
if value has default or is set

getNeededReference

public ParameterSet getNeededReference()
Returns a reference to a ParameterSet whose ParameterSet.hasDefaultOrIsSet() method depends on the value of this Parameter. If no such ParameterSet exists, null is returned.

Returns:
the reference

getNeededReferenceId

public Long getNeededReferenceId()
Returns the id of the ParameterSet that would be returned by getNeededReference().

Returns:
the id

setNeededReference

public void setNeededReference(ParameterSet reference)
Sets an internal reference to a ParameterSet whose validity depends on the value of this Parameter.

Parameters:
reference - the ParameterSet depending on the value of this Parameter

isSet

public abstract boolean isSet()
Returns true if the parameter was set by the user.

Returns:
if the parameter was set

isAtomic

public abstract boolean isAtomic()
Returns true if the parameter is of an atomic data type

Returns:
if the parameter is atomic

getErrorMessage

public abstract String getErrorMessage()
If a value could not be set successfully this method returns the corresponding error message.

Returns:
the error message

simplify

public abstract void simplify()
Simplifies the Parameter and its contents to the relevant information. This could be e.g. to reset the contents of those values of a CollectionParameter that are not selected.


reset

public abstract void reset()
Resets the parameter and its contents to the default values or null if not defaults are given.


clone

public Parameter clone()
                throws CloneNotSupportedException
Overrides:
clone in class Object
Throws:
CloneNotSupportedException

setDefault

public abstract void setDefault(Object defaultValue)
                         throws Exception
Sets the default value of the parameter to defaultValue

Parameters:
defaultValue - the default value
Throws:
Exception - throws an Exceptio if the default value is not an appropriate value for this parameter.

setParent

public void setParent(ParameterSet parent)
Sets the reference of the enclosing ParameterSet of this Parameter to parent.

Parameters:
parent - the new enclosing ParameterSet

getParent

public ParameterSet getParent()
Returns a reference to the ParameterSet enclosing this Parameter.

Returns:
the enclosing ParameterSet

fromXML

protected void fromXML(StringBuffer source)
                throws NonParsableException
Parses a Parameter from an XML-representation as returned by toXML().

Parameters:
source - the XML-representation
Throws:
NonParsableException - is thrown if the XML-code could not be parsed

toXML

public StringBuffer toXML()
Description copied from interface: Storable
This method returns an XML-representation of an instance of the implementing class.

Specified by:
toXML in interface Storable
Returns:
the XML-representation