de.jstacs.parameters
Class RangeParameter

java.lang.Object
  extended by de.jstacs.parameters.Parameter
      extended by de.jstacs.parameters.RangeParameter
All Implemented Interfaces:
RangeIterator, Storable, Cloneable

public class RangeParameter
extends Parameter
implements RangeIterator

Class for a parameter wrapper that allows SimpleParameters to be set to a set of values.
These values may be given either as a list of values separated by spaces, as a range between a first and a last value with a given number of steps between these values, or a single value. In the latter case a RangeParameter works just like a plain SimpleParameter. SimpleParameters that are used to construct a RangeParameter must be rangeable, i.e. their isRangeable()-method must return true, or they will be rejected.

Author:
Jan Grau, Jens Keilwagen

Nested Class Summary
static class RangeParameter.RangeType
          The possible types of defining ranges for a RangeParameter
static class RangeParameter.Scale
          The possible scales, if RangeParameter.RangeType is RangeParameter.RangeType.RANGE.
 
Field Summary
 
Fields inherited from class de.jstacs.parameters.Parameter
neededReference, neededReferenceId, parent
 
Constructor Summary
RangeParameter(SimpleParameter par)
          Constructs a RangeParameter from a SimpleParameter that is rangeable.
RangeParameter(StringBuffer representation)
          Restores a RangeParameter from its XML-representation.
 
Method Summary
 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
 RangeParameter clone()
           
protected  void fromXML(StringBuffer representation)
          Parses a Parameter from an XML-representation as returned by Parameter.toXML().
static CollectionParameter getCollectionOfScales()
          Returns a CollectionsParameter that allows the user to choose between different scales.
 String getComment()
          Returns a comment on this parameter that tells something about useful values, domains, usage of this parameter, etc.
 DataType getDatatype()
          Returns the data type of the parameter
 Object getEndValue()
          Returns the last value of a range of parameter values or null if no range was specified.
 String getErrorMessage()
          If a value could not be set successfully this method returns the corresponding error message.
 String getList()
          Returns a list of all parameter values as a String or null if no parameter values have been set.
 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.
 int getNumberOfNexts(int afterIndex)
          Returns the number of calls to next() that can be done, before obtaining false.
 int getNumberOfValues()
          Returns the number of values in a list or range of parameter values
 String getScale()
          Returns a description of the the scale of a range of parameter values.
 Object getStartValue()
          Returns the start value of a range of parameter values or null if no range was specified.
 int getSteps()
          Returns the number of steps of a range of parameter values or 0 if no range was specified.
 Object getValue()
          Returns the current value of this Parameter
 boolean hasDefaultOrIsSet()
          Returns true if the parameter either has a default value or the value was set by the user.
 boolean isAtomic()
          Returns true if the parameter is of an atomic data type
 boolean isRanged()
          Returns true if this range iterator is ranging over a set of values.
 boolean isRequired()
          Returns true if the parameter is required, false otherwise
 boolean isSet()
          Returns true if the parameter was set by the user.
 boolean next()
          Returns true if the next element still exists and get be fetched using getValue(), false otherwise
 void reset()
          Resets the parameter and its contents to the default values or null if not defaults are given.
 void resetToFirst()
          Resets the current value in the collection to the first value.
 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 setShallBeRanged(RangeParameter.RangeType shallBeRanged)
          Sets the type of this RangeParameter to one of LIST, RANGE, or NO.
 void setValue(Object value)
          Sets the value of this parameter to value.
 void setValues(Object startValue, int steps, Object endValue, RangeParameter.Scale scale)
          Sets the values of this RangeParameter as a range of values, specified by a start values, a last value, a number of steps between these values (without the last value), and a scale in that the values between the first and the last value are chosen.
 void setValues(String values)
          Sets a list of values from a String containing a space separated list of values.
 void setValuesInLogScale(boolean log, double radix, Object startValue, int steps, Object endValue)
          This method enables you to set a list of values in an easy manner.
 RangeParameter.RangeType shallBeRanged()
          Returns one of LIST, RANGE, or NO depending on the input used to specify this RangeParameter
 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.
 String valuesToString()
          Returns a String-representation of the set of values.
 
Methods inherited from class de.jstacs.parameters.Parameter
getId, getNeededReferenceId, getParent, setParent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RangeParameter

public RangeParameter(SimpleParameter par)
               throws Exception
Constructs a RangeParameter from a SimpleParameter that is rangeable.

Parameters:
par - the parameter
Throws:
Exception - an Exception is thrown if the parameter is not rangeable, i.e. its isRangeable()-method returns false.

RangeParameter

public RangeParameter(StringBuffer representation)
               throws NonParsableException
Restores a RangeParameter from its XML-representation.

Parameters:
representation - the XML-representation
Throws:
NonParsableException - a NonParsableException is thrown if representation could not be parsed
Method Detail

clone

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

getCollectionOfScales

public static CollectionParameter getCollectionOfScales()
                                                 throws ParameterException
Returns a CollectionsParameter that allows the user to choose between different scales.

Returns:
the CollectionParameter
Throws:
ParameterException - is thrown if the CollectionParameter could, or if one of the possible values of the CollectionParameter was not legal

getName

public String getName()
Description copied from class: Parameter
Returns the name of the parameter

Specified by:
getName in class Parameter
Returns:
the name

getList

public String getList()
Returns a list of all parameter values as a String or null if no parameter values have been set.

Returns:
the list

getStartValue

public Object getStartValue()
Returns the start value of a range of parameter values or null if no range was specified.

Returns:
the start value

getEndValue

public Object getEndValue()
Returns the last value of a range of parameter values or null if no range was specified.

Returns:
the last value

getSteps

public int getSteps()
Returns the number of steps of a range of parameter values or 0 if no range was specified.

Returns:
the number of steps

getScale

public String getScale()
Returns a description of the the scale of a range of parameter values.

Returns:
the description

getDatatype

public DataType getDatatype()
Description copied from class: Parameter
Returns the data type of the parameter

Specified by:
getDatatype in class Parameter
Returns:
the data type

getComment

public String getComment()
Description copied from class: Parameter
Returns a comment on this parameter that tells something about useful values, domains, usage of this parameter, etc.

Specified by:
getComment in class Parameter
Returns:
the comment

isRequired

public boolean isRequired()
Description copied from class: Parameter
Returns true if the parameter is required, false otherwise

Specified by:
isRequired in class Parameter
Returns:
if the parameter is required

checkValue

public boolean checkValue(Object value)
Description copied from class: Parameter
Checks the value for correctness, e.g. for numerical parameters this might be checking if the value is within specified bounds

Specified by:
checkValue in class Parameter
Parameters:
value - the value to be checked
Returns:
if the value is valid

setValue

public void setValue(Object value)
              throws SimpleParameter.IllegalValueException
Description copied from class: Parameter
Sets the value of this parameter to value.

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

setValues

public void setValues(String values)
               throws SimpleParameter.IllegalValueException
Sets a list of values from a String containing a space separated list of values. After this method has been called, shallBeRanged() returns LIST.

Parameters:
values - the space separated list
Throws:
SimpleParameter.IllegalValueException - an IllegalValueException is thrown if at least one of the values in the list is no suitable value for this RangeParameter

setValues

public void setValues(Object startValue,
                      int steps,
                      Object endValue,
                      RangeParameter.Scale scale)
               throws SimpleParameter.IllegalValueException
Sets the values of this RangeParameter as a range of values, specified by a start values, a last value, a number of steps between these values (without the last value), and a scale in that the values between the first and the last value are chosen. This range must be one of LINSCALE, LOGSCALE, and EXPSCALE

Parameters:
startValue - the first value
steps - the number of steps
endValue - the last values
scale - the scale
Throws:
SimpleParameter.IllegalValueException - an IllegalValueException is thrown if one of the values is not suitable for this RangeParameter, e.g. is out of a specified range of allowed values

setValuesInLogScale

public void setValuesInLogScale(boolean log,
                                double radix,
                                Object startValue,
                                int steps,
                                Object endValue)
                         throws SimpleParameter.IllegalValueException
This method enables you to set a list of values in an easy manner. The values of the list are from the interval [startValue,endValue] in (inverse) log scale.

Parameters:
log - if true log scale is used, otherwise inverse log scale
radix - the radix for the scale
startValue - the start value
steps - the number of steps
endValue - the end value
Throws:
SimpleParameter.IllegalValueException - if some constraints are not fulfilled

getValue

public Object getValue()
Description copied from class: Parameter
Returns the current value of this Parameter

Specified by:
getValue in class Parameter
Returns:
the current value

next

public boolean next()
             throws SimpleParameter.IllegalValueException
Returns true if the next element still exists and get be fetched using getValue(), false otherwise

Specified by:
next in interface RangeIterator
Returns:
if the next element exists
Throws:
SimpleParameter.IllegalValueException

getNumberOfValues

public int getNumberOfValues()
Returns the number of values in a list or range of parameter values

Specified by:
getNumberOfValues in interface RangeIterator
Returns:
the number of values

getNumberOfNexts

public int getNumberOfNexts(int afterIndex)
Returns the number of calls to next() that can be done, before obtaining false.

Parameters:
afterIndex - the index after which next() shall be called
Returns:
the number of calls

shallBeRanged

public RangeParameter.RangeType shallBeRanged()
Returns one of LIST, RANGE, or NO depending on the input used to specify this RangeParameter

Returns:
the type of specification

setShallBeRanged

public void setShallBeRanged(RangeParameter.RangeType shallBeRanged)
                      throws Exception
Sets the type of this RangeParameter to one of LIST, RANGE, or NO.

Parameters:
shallBeRanged - the type of this parameter
Throws:
Exception - an Exception is thrown if shallBeRanged is none of the allowed values

hasDefaultOrIsSet

public boolean hasDefaultOrIsSet()
Description copied from class: Parameter
Returns true if the parameter either has a default value or the value was set by the user.

Specified by:
hasDefaultOrIsSet in class Parameter
Returns:
if value has default or is set

isSet

public boolean isSet()
Description copied from class: Parameter
Returns true if the parameter was set by the user.

Specified by:
isSet in class Parameter
Returns:
if the parameter was set

isAtomic

public boolean isAtomic()
Description copied from class: Parameter
Returns true if the parameter is of an atomic data type

Specified by:
isAtomic in class Parameter
Returns:
if the parameter is atomic

getErrorMessage

public String getErrorMessage()
Description copied from class: Parameter
If a value could not be set successfully this method returns the corresponding error message.

Specified by:
getErrorMessage in class Parameter
Returns:
the error message

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
Overrides:
toXML in class Parameter
Returns:
the XML-representation

fromXML

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

Overrides:
fromXML in class Parameter
Parameters:
representation - the XML-representation
Throws:
NonParsableException - is thrown if the XML-code could not be parsed

simplify

public void simplify()
Description copied from class: Parameter
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.

Specified by:
simplify in class Parameter

reset

public void reset()
Description copied from class: Parameter
Resets the parameter and its contents to the default values or null if not defaults are given.

Specified by:
reset in class Parameter

resetToFirst

public void resetToFirst()
Description copied from interface: RangeIterator
Resets the current value in the collection to the first value.

Specified by:
resetToFirst in interface RangeIterator

setDefault

public void setDefault(Object defaultValue)
                throws Exception
Description copied from class: Parameter
Sets the default value of the parameter to defaultValue

Specified by:
setDefault in class Parameter
Parameters:
defaultValue - the default value
Throws:
Exception - throws an Exceptio if the default value is not an appropriate value for this parameter.

valuesToString

public String valuesToString()
Description copied from interface: RangeIterator
Returns a String-representation of the set of values.

Specified by:
valuesToString in interface RangeIterator
Returns:
the representation

isRanged

public boolean isRanged()
Description copied from interface: RangeIterator
Returns true if this range iterator is ranging over a set of values.

Specified by:
isRanged in interface RangeIterator
Returns:
if ranging

getNeededReference

public ParameterSet getNeededReference()
Description copied from class: Parameter
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.

Overrides:
getNeededReference in class Parameter
Returns:
the reference

setNeededReference

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

Overrides:
setNeededReference in class Parameter
Parameters:
reference - the ParameterSet depending on the value of this Parameter