de.jstacs.parameters
Class RangeParameter

java.lang.Object
  de.jstacs.AnnotatedEntity
      de.jstacs.parameters.Parameter
          de.jstacs.parameters.RangeParameter

All Implemented Interfaces:

GalaxyConvertible, RangeIterator, Storable, Cloneable

public class RangeParameter
extends Parameter
implements RangeIterator, GalaxyConvertible

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 method SimpleParameter.isRangeable() 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 This enum defines possible scales, if RangeParameter.RangeType is RangeParameter.RangeType.RANGE.

Field Summary

Fields inherited from class de.jstacs.parameters.Parameter

parent

Fields inherited from class de.jstacs.AnnotatedEntity

comment, datatype, name

Constructor Summary

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

RangeParameter(StringBuffer representation)
The standard constructor for the interface Storable.

Method Summary

protected void	appendFurtherInfos(StringBuffer buf) This method can be used in the method Storable.toXML() to extract further information (name, comment, datatype).
boolean	checkValue(Object value) Checks the value for correctness, e.g.
RangeParameter	clone()
protected void	extractFurtherInfos(StringBuffer buf) This method can be used in the constructor with parameter StringBuffer to extract the further information.
void	fromGalaxy(String namePrefix, StringBuffer command) Parses the contents of command in the format defined by configBuffer of GalaxyConvertible.toGalaxy(String, String, int, StringBuffer, StringBuffer, boolean) and sets the values of the Parameter or ParameterSet accordingly.
static EnumParameter	getCollectionOfScales() Returns a EnumParameter that allows the user to choose between different scales.
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.
int	getNumberOfNexts(int afterIndex) Returns the number of calls of 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 value of the AnnotatedEntity.
String	getXMLTag() This method returns a tag used as outer tag of the XML description.
boolean	hasDefaultOrIsSet() Returns true if the parameter either has a default value or the value was set by the user, false otherwise.
boolean	isAtomic() Returns true if the parameter is of an atomic data type, false otherwise.
boolean	isRanged() Returns true if this RangeIterator 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, false otherwise.
boolean	next() Returns true if the next element still exists and can be fetched using getValue(), false otherwise.
void	reset() Resets the parameter and its contents to the default values or null if no 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	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 value, 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	toGalaxy(String namePrefix, String configPrefix, int depth, StringBuffer descBuffer, StringBuffer configBuffer, boolean addLine) Creates an Galaxy XML-representation of the parameters and appends it to descBuffer and variable configuration and appends it to configBuffer.
String	valuesToString() Returns a String representation of the set of values.

Methods inherited from class de.jstacs.parameters.Parameter

getParent, isComparable, setParent

Methods inherited from class de.jstacs.AnnotatedEntity

getComment, getDatatype, getName, toXML

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 rangeable SimpleParameter

Throws:

Exception - if the SimpleParameter is not rangeable, i.e. its method SimpleParameter.isRangeable() returns false

RangeParameter

public RangeParameter(StringBuffer representation)
               throws NonParsableException

The standard constructor for the interface Storable. Restores a RangeParameter from its XML representation.

Parameters:

representation - the XML representation as StringBuffer

Throws:

NonParsableException - if the StringBuffer representation could not be parsed

Method Detail

clone

public RangeParameter clone()
                     throws CloneNotSupportedException

Overrides:

clone in class Parameter

Throws:

CloneNotSupportedException

getCollectionOfScales

public static EnumParameter getCollectionOfScales()
                                           throws ParameterException

Returns a EnumParameter that allows the user to choose between different scales.

Returns:

the EnumParameter

Throws:

ParameterException - if the EnumParameter could, or if one of the possible values of the SelectionParameter was not legal

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 of all parameter values or null

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 of a range of parameter values or null

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 of a range of parameter values or null

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 of a range of parameter values or 0

getScale

public String getScale()

Returns a description of the the scale of a range of parameter values.

Returns:

the description of the the scale of a range of parameter values

See Also:

RangeParameter.Scale

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:

true if the Parameter is required, false otherwise

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:

true if the value is valid, false otherwise

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 of the Parameter

Throws:

SimpleParameter.IllegalValueException - if the specified value is not valid for this Parameter

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 RangeParameter.RangeType.LIST.

Parameters:

values - the space separated list of values

Throws:

SimpleParameter.IllegalValueException - if at least one of the values in the list is not suitable 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 value, 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 scale must be one of those listed in RangeParameter.Scale.

Parameters:

startValue - the first value of the range

steps - the number of steps between startValue and endValue (exclusive)

endValue - the last value of the range

scale - the RangeParameter.Scale

Throws:

SimpleParameter.IllegalValueException - if one of the values is not suitable for this RangeParameter, e.g. is out of a specified range of allowed values

See Also:

RangeParameter.Scale

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) logarithmic scale.

Parameters:

log - if true a logarithmic scale is used, otherwise the inverse logarithmic scale

radix - the radix for the scale

startValue - the first value of the range

steps - the number of steps between startValue and endValue (exclusive)

endValue - the last value of the range

Throws:

SimpleParameter.IllegalValueException - if some constraints are not fulfilled

getValue

public Object getValue()

Description copied from class: AnnotatedEntity

Returns the value of the AnnotatedEntity.

Specified by:

getValue in class AnnotatedEntity

Returns:

the value of the AnnotatedEntity

next

public boolean next()
             throws SimpleParameter.IllegalValueException

Returns true if the next element still exists and can be fetched using getValue(), false otherwise.

Specified by:

next in interface RangeIterator

Returns:

true if the next element exists and can be fetched, false otherwise

Throws:

SimpleParameter.IllegalValueException - if the next value to be fetched is not valid

See Also:

setValue(Object)

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 of next() that can be done before obtaining false.

Parameters:

afterIndex - the index after which next() shall be called

Returns:

the number of possible calls of next() after afterIndex

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 range specification

See Also:

RangeParameter.RangeType

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, false otherwise.

Specified by:

hasDefaultOrIsSet in class Parameter

Returns:

true if value has a default value or was set, false otherwise

isSet

public boolean isSet()

Description copied from class: Parameter

Returns true if the parameter was set by the user, false otherwise.

Specified by:

isSet in class Parameter

Returns:

true if the parameter was set, false otherwise

isAtomic

public boolean isAtomic()

Description copied from class: Parameter

Returns true if the parameter is of an atomic data type, false otherwise.

Specified by:

isAtomic in class Parameter

Returns:

true if the parameter is atomic, false otherwise

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:

an error message if a value could not be set successfully

getXMLTag

public String getXMLTag()

Description copied from class: AnnotatedEntity

This method returns a tag used as outer tag of the XML description.

Specified by:

getXMLTag in class AnnotatedEntity

Returns:

a tag used as outer tag of the XML description

appendFurtherInfos

protected void appendFurtherInfos(StringBuffer buf)

Description copied from class: AnnotatedEntity

This method can be used in the method Storable.toXML() to extract further information (name, comment, datatype).

Overrides:

appendFurtherInfos in class Parameter

Parameters:

buf - a XML representation of the main information as StringBuffer

See Also:

Storable.toXML()

extractFurtherInfos

protected void extractFurtherInfos(StringBuffer buf)
                            throws NonParsableException

Description copied from class: AnnotatedEntity

This method can be used in the constructor with parameter StringBuffer to extract the further information.

Overrides:

extractFurtherInfos in class Parameter

Parameters:

buf - a XML represenation of the main information as StringBuffer

Throws:

NonParsableException - if the XML representation is not parsable

See Also:

AnnotatedEntity.AnnotatedEntity(StringBuffer)

reset

public void reset()

Description copied from class: Parameter

Resets the parameter and its contents to the default values or null if no 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. This method also sets the current value of this Parameter to the default.

Specified by:

setDefault in class Parameter

Parameters:

defaultValue - the default value

Throws:

Exception - 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 String representation

isRanged

public boolean isRanged()

Description copied from interface: RangeIterator

Returns true if this RangeIterator is ranging over a set of values.

Specified by:

isRanged in interface RangeIterator

Returns:

true if this RangeIterator is ranging over a set of values, false otherwise

toGalaxy

public void toGalaxy(String namePrefix,
                     String configPrefix,
                     int depth,
                     StringBuffer descBuffer,
                     StringBuffer configBuffer,
                     boolean addLine)
              throws Exception

Description copied from interface: GalaxyConvertible

Creates an Galaxy XML-representation of the parameters and appends it to descBuffer and variable configuration and appends it to configBuffer. The variable configuration is also used to parse user-supplied values returned by Galaxy.

Specified by:

toGalaxy in interface GalaxyConvertible

Parameters:

namePrefix - the prefix of the variable name used in Galaxy

configPrefix - the prefix for conditionals

depth - the depth in the parameter hierarchy, used for graphical representation of nesting

descBuffer - the buffer for the parameter description

configBuffer - the buffer for the configuration line

addLine - if true, a line is added before the title of a parameter

Throws:

Exception - if the conversion fails

fromGalaxy

public void fromGalaxy(String namePrefix,
                       StringBuffer command)
                throws Exception

Description copied from interface: GalaxyConvertible

Parses the contents of command in the format defined by configBuffer of GalaxyConvertible.toGalaxy(String, String, int, StringBuffer, StringBuffer, boolean) and sets the values of the Parameter or ParameterSet accordingly.

Specified by:

fromGalaxy in interface GalaxyConvertible

Parameters:

namePrefix - the prefix of the variable name

command - the command string

Throws:

Exception - if the command string could not be parsed