de.jstacs.parameters
Class AbstractSelectionParameter

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

All Implemented Interfaces:

GalaxyConvertible, Rangeable, Storable, Cloneable

Direct Known Subclasses:

MultiSelectionParameter, SelectionParameter

public abstract class AbstractSelectionParameter
extends Parameter
implements Rangeable, GalaxyConvertible

Class for a collection parameter, i.e. a parameter that provides some collection of possible values the user can choose from. Instances of this class can be used as parameters in a ParameterSet.

Author:

Jens Keilwagen, Jan Grau

See Also:

ParameterSet

Nested Class Summary

class

AbstractSelectionParameter.InconsistentCollectionException This exception is thrown if the AbstractSelectionParameter is inconsistent for some reason.

Field Summary

protected String	errorMessage If a value was illegal for the collection parameter, this field holds the error message.
protected ParameterSet	parameters The internal ParameterSet that holds the possible values
protected boolean	userSelected true if the user has selected an item

Fields inherited from class de.jstacs.parameters.Parameter

parent

Fields inherited from class de.jstacs.AnnotatedEntity

comment, datatype, name

Constructor Summary

AbstractSelectionParameter(DataType datatype, String[] keys, Object[] values, String[] comments, String name, String comment, boolean required)
Constructor for a AbstractSelectionParameter.

AbstractSelectionParameter(DataType datatype, String[] keys, Object[] values, String name, String comment, boolean required)
Constructor for a AbstractSelectionParameter of SimpleParameters.

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

AbstractSelectionParameter(String name, String comment, boolean required, Class<? extends ParameterSet>... values)
Constructor for a AbstractSelectionParameter from an array of Classes of ParameterSets.

AbstractSelectionParameter(String name, String comment, boolean required, ParameterSet... values)
Constructor for a AbstractSelectionParameter from an array of ParameterSets.

Method Summary

protected void	appendFurtherInfos(StringBuffer buf) This method can be used in the method Storable.toXML() to extract further information (name, comment, datatype).
protected int	check(Object value) Test whether a given value can be used in Parameter.setValue(Object).
boolean	checkValue(Object value) Returns true if the key specified by value is in the set of keys of this AbstractSelectionParameter.
AbstractSelectionParameter	clone()
protected void	createParameterSet(Object[] values, String[] keys, String[] comments) Creates a new ParameterSet from an array of values, an array of names and an array of comments.
boolean	equals(Object o2)
protected void	extractFurtherInfos(StringBuffer representation) This method can be used in the constructor with parameter StringBuffer to extract the further information.
String	getErrorMessage() If a value could not be set successfully this method returns the corresponding error message.
ParameterSet	getParametersInCollection() Returns the possible values in this collection.
MultiSelectionParameter	getRangedInstance() Returns an instance of RangeIterator that has the same properties as the current instance, but accepts a range or list of values.
abstract boolean	hasDefault() Returns true, if this AbstractSelectionParameter has a default value.
boolean	isAtomic() Returns true if the parameter is of an atomic data type, false otherwise.
boolean	isRangeable() Returns true if the parameters can be varied over a range of values.
boolean	isRequired() Returns true if the Parameter is required, false otherwise.
abstract boolean	isSelected(int idx) Returns true if the option at position idx is selected.
boolean	isSet() Returns true if the parameter was set by the user, false otherwise.
boolean	isUserSelected() Returns true if the value was selected by the user.
abstract void	setDefault(Object defaultValue) Sets the default value of this AbstractSelectionParameter to defaultValue.
void	setRangeable(boolean rangeable) Sets the value returned by isRangeable() to rangeable.
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.

Methods inherited from class de.jstacs.parameters.Parameter

getParent, hasDefaultOrIsSet, isComparable, reset, setParent, setValue

Methods inherited from class de.jstacs.AnnotatedEntity

getComment, getDatatype, getName, getValue, getXMLTag, toXML

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface de.jstacs.parameters.GalaxyConvertible

fromGalaxy

Field Detail

parameters

protected ParameterSet parameters

The internal ParameterSet that holds the possible values

userSelected

protected boolean userSelected

true if the user has selected an item

errorMessage

protected String errorMessage

If a value was illegal for the collection parameter, this field holds the error message.

Constructor Detail

AbstractSelectionParameter

public AbstractSelectionParameter(DataType datatype,
                                  String[] keys,
                                  Object[] values,
                                  String name,
                                  String comment,
                                  boolean required)
                           throws AbstractSelectionParameter.InconsistentCollectionException,
                                  SimpleParameter.IllegalValueException,
                                  SimpleParameter.DatatypeNotValidException

Constructor for a AbstractSelectionParameter of SimpleParameters.

Parameters:

datatype - the data type of the parameters in the collection

keys - the keys/names of the values in the collection, this is the name the user will see in the user interface

values - the values the names stand for, this array must be of the same length as keys, a key at a certain position belongs to the value at the same position in the array

name - the name of the parameter

comment - a comment on the parameter

required - true if this AbstractSelectionParameter is required, false otherwise

Throws:

AbstractSelectionParameter.InconsistentCollectionException - if the length of keys and the values is different or the collection is inconsistent for some other reason

SimpleParameter.IllegalValueException - if one of the values in values is not of type datatype

SimpleParameter.DatatypeNotValidException - if the datatype is not one of the allowed values

See Also:

AbstractSelectionParameter(DataType, String[], Object[], String[], String, String, boolean), SimpleParameter

AbstractSelectionParameter

public AbstractSelectionParameter(DataType datatype,
                                  String[] keys,
                                  Object[] values,
                                  String[] comments,
                                  String name,
                                  String comment,
                                  boolean required)
                           throws AbstractSelectionParameter.InconsistentCollectionException,
                                  SimpleParameter.IllegalValueException,
                                  SimpleParameter.DatatypeNotValidException

Constructor for a AbstractSelectionParameter.

Parameters:

datatype - the data type of the parameters in the collection

keys - the keys/names of the values in the collection, this is the name the user will see in the user interface

values - the values the names stand for, this array must be of the same length as keys, a key at a certain position belongs to the value at the same position in the array

comments - the comments on the possible values

name - the name of the parameter

comment - a comment on the parameter

required - true if the AbstractSelectionParameter is required, false otherwise

Throws:

AbstractSelectionParameter.InconsistentCollectionException - if the length of keys and values is different or the collection is inconsistent for some other reason

SimpleParameter.IllegalValueException - if one of the values in values is not of type datatype

SimpleParameter.DatatypeNotValidException - if the datatype is not one of the allowed values

See Also:

createParameterSet(Object[], String[], String[])

AbstractSelectionParameter

public AbstractSelectionParameter(String name,
                                  String comment,
                                  boolean required,
                                  ParameterSet... values)

Constructor for a AbstractSelectionParameter from an array of ParameterSets. This constructor can be used to easily construct a AbstractSelectionParameter that lets the user select from a list of possible options that all require an own set of Parameters to be instantiated.

Parameters:

values - the array of ParameterSets

name - the name of the parameter

comment - a comment on the parameter

required - true if the parameter is required, false otherwise

See Also:

createParameterSet(Object[], String[], String[]), ParameterSet.getName(ParameterSet), ParameterSet.getComment(ParameterSet)

AbstractSelectionParameter

public AbstractSelectionParameter(String name,
                                  String comment,
                                  boolean required,
                                  Class<? extends ParameterSet>... values)

Constructor for a AbstractSelectionParameter from an array of Classes of ParameterSets. This constructor can be used to easily construct a AbstractSelectionParameter that lets the user select from a list of possible options that all require an own set of Parameters to be instantiated. It is the lazy evaluation variant of AbstractSelectionParameter(String, String, boolean, ParameterSet...), i.e., the ParameterSets are only created if necessary.

Parameters:

values - the array of Classes of ParameterSets

name - the name of the parameter

comment - a comment on the parameter

required - true if the parameter is required, false otherwise

See Also:

createParameterSet(Object[], String[], String[]), ParameterSet.getName(ParameterSet), ParameterSet.getComment(ParameterSet)

AbstractSelectionParameter

public AbstractSelectionParameter(StringBuffer representation)
                           throws NonParsableException

The standard constructor for the interface Storable. Restores an instance of AbstractSelectionParameter from a XML representation.

Parameters:

representation - the XML representation as StringBuffer

Throws:

NonParsableException - if the StringBuffer representation could not be parsed

Method Detail

createParameterSet

protected void createParameterSet(Object[] values,
                                  String[] keys,
                                  String[] comments)
                           throws SimpleParameter.DatatypeNotValidException,
                                  SimpleParameter.IllegalValueException,
                                  AbstractSelectionParameter.InconsistentCollectionException

Creates a new ParameterSet from an array of values, an array of names and an array of comments.

Parameters:

values - the values the names stand for, this array must be of the same length as keys, a key at a certain position belongs to the value at the same position in the array

keys - the keys/names of the values in the collection, this is the name the user will see in the user interface

comments - the comments on the possible values

Throws:

SimpleParameter.IllegalValueException - if one of the values in values is not of type datatype

SimpleParameter.DatatypeNotValidException - if the data type is not allowed, i.e. is not one of the primitive data types, String or DataType.PARAMETERSET

AbstractSelectionParameter.InconsistentCollectionException - if the internally used keys are not unique

clone

public AbstractSelectionParameter clone()
                                 throws CloneNotSupportedException

Overrides:

clone in class Parameter

Throws:

CloneNotSupportedException

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

hasDefault

public abstract boolean hasDefault()

Returns true, if this AbstractSelectionParameter has a default value.

Returns:

if this AbstractSelectionParameter has a default value

See Also:

setDefault(Object)

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

getParametersInCollection

public ParameterSet getParametersInCollection()

Returns the possible values in this collection.

Returns:

the values/parameters in this collection

setRangeable

public void setRangeable(boolean rangeable)

Sets the value returned by isRangeable() to rangeable.

Parameters:

rangeable - the new value

isRangeable

public boolean isRangeable()

Description copied from interface: Rangeable

Returns true if the parameters can be varied over a range of values.

Specified by:

isRangeable in interface Rangeable

Returns:

true if the parameter can be varied, false otherwise

check

protected int check(Object value)

Test whether a given value can be used in Parameter.setValue(Object). If so, the index of corresponding option is returned, otherwise -1.

Parameters:

value - the value to be checked

Returns:

the index of the corresponding option or -1 if there's no corresponding option

See Also:

errorMessage, checkValue(Object)

checkValue

public boolean checkValue(Object value)

Returns true if the key specified by value is in the set of keys of this AbstractSelectionParameter.

Specified by:

checkValue in class Parameter

Parameters:

value - the value to be checked

Returns:

true if the key specified by value is in the set of keys of this AbstractSelectionParameter, 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

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 representation)
                            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:

representation - a XML represenation of the main information as StringBuffer

Throws:

NonParsableException - if the XML representation is not parsable

See Also:

AnnotatedEntity.AnnotatedEntity(StringBuffer)

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

isSelected

public abstract boolean isSelected(int idx)

Returns true if the option at position idx is selected.

Parameters:

idx - the position

Returns:

true if the option at position idx is selected, false otherwise

isUserSelected

public boolean isUserSelected()

Returns true if the value was selected by the user.

Returns:

true if the value was selected by the user.

setDefault

public abstract void setDefault(Object defaultValue)
                         throws Exception

Sets the default value of this AbstractSelectionParameter to defaultValue. This method also sets the current value of this AbstractSelectionParameter to the default and resets it such that isUserSelected() returns false.

Specified by:

setDefault in class Parameter

Parameters:

defaultValue - the default value

Throws:

AbstractSelectionParameter.InconsistentCollectionException - if the default value is not an appropriate value for this Parameter

Exception

equals

public boolean equals(Object o2)

Overrides:

equals in class Object

getRangedInstance

public MultiSelectionParameter getRangedInstance()
                                          throws Exception

Description copied from interface: Rangeable

Returns an instance of RangeIterator that has the same properties as the current instance, but accepts a range or list of values. These values can be obtained by the methods of RangeIterator.

Specified by:

getRangedInstance in interface Rangeable

Returns:

an instance with the same properties as the current instance

Throws:

Exception - is thrown if Rangeable.isRangeable() returns false or the ranged instance could not be created for some other reason

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