de.jstacs.parameters
Class CollectionParameter

java.lang.Object
  de.jstacs.parameters.Parameter
      de.jstacs.parameters.CollectionParameter

All Implemented Interfaces:

GalaxyConvertible, Rangeable, Storable, Cloneable

Direct Known Subclasses:

EnumParameter, MultiSelectionCollectionParameter

public class CollectionParameter
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:

Jan Grau

See Also:

ParameterSet

Nested Class Summary

class

CollectionParameter.InconsistentCollectionException This exception is thrown if the CollectionParameter 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

neededReference, neededReferenceId, parent

Constructor Summary

	CollectionParameter(DataType datatype, String[] keys, Object[] values, String[] comments, String name, String comment, boolean required) Constructor for a CollectionParameter.
	CollectionParameter(DataType datatype, String[] keys, Object[] values, String name, String comment, boolean required) Constructor for a CollectionParameter.
	CollectionParameter(InstanceParameterSet[] values, String name, String comment, boolean required) Constructor for a CollectionParameter from an array of ParameterSets.
	CollectionParameter(ParameterSet[] values, String[] keys, String[] comments, String name, String comment, boolean required) Constructor for a CollectionParameter from an array of ParameterSets.
protected	CollectionParameter(ParameterSet options, int selected, int defaultSelected, boolean userSelected, String name, String comment, boolean required, DataType datatype, String errorMessage, boolean rangeable) Creates a new CollectionParameter from the necessary field.
	CollectionParameter(StringBuffer representation) The standard constructor for the interface Storable.

Method Summary

protected void	appendCollection(StringBuffer buf) Appends the internal ParameterSet in its XML representation ( ParameterSet.toXML()) to the StringBuffer buf.
boolean	checkValue(Object value) Returns true if the key specified by value is in the set of keys of this CollectionParameter.
CollectionParameter	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	extractCollection(StringBuffer buf) Extracts the internal ParameterSet from its XML representation ( ParameterSet.toXML()).
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) and sets the values of the Parameter or ParameterSet accordingly.
protected void	fromXML(StringBuffer representation) Parses a Parameter from a XML representation as returned by Parameter.toXML().
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.
protected int	getDefault() Returns the index of the default selected value.
String	getErrorMessage() If a value could not be set successfully this method returns the corresponding error message.
String	getName() Returns the name of the Parameter.
ParameterSet	getParametersInCollection() Returns the possible values in this collection.
Parameter	getRangedInstance() Returns an instance of RangeIterator that has the same properties as the current instance, but accepts a range or list of values.
int	getSelected() Returns the index of the selected value.
Object	getValue() Returns the current value of this Parameter.
boolean	hasDefault() Returns true, if this CollectionParameter has a default value.
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	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.
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.
void	reset() Resets the parameter and its contents to the default values or null if no defaults are given.
void	setDefault(Object defaultValue) Sets the default value of the Parameter to defaultValue.
void	setRangeable(boolean rangeable) Sets the value returned by isRangeable() to rangeable.
void	setValue(Object value) Sets the selected value to the one that is specified by the key value.
void	simplify() Simplifies the Parameter and its contents to the relevant information.
void	toGalaxy(String namePrefix, String configPrefix, int depth, StringBuffer descBuffer, StringBuffer configBuffer) Creates an Galaxy XML-representation of the parameters and appends it to descBuffer and variable configuration and appends it to configBuffer.
String	toString()
StringBuffer	toXML() This method returns an XML representation as StringBuffer of an instance of the implementing class.

Methods inherited from class de.jstacs.parameters.Parameter

getId, getNeededReference, getNeededReferenceId, getParent, setNeededReference, setParent

Methods inherited from class java.lang.Object

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

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

CollectionParameter

protected CollectionParameter(ParameterSet options,
                              int selected,
                              int defaultSelected,
                              boolean userSelected,
                              String name,
                              String comment,
                              boolean required,
                              DataType datatype,
                              String errorMessage,
                              boolean rangeable)

Creates a new CollectionParameter from the necessary field. This constructor should be used to clone a current instance.

Parameters:

options - the options of the CollectionParameter

selected - the currently selected value

defaultSelected - the value selected by default

userSelected - true if the current value was selected by the user, false otherwise

name - the name of the parameter

comment - a comment on the parameter

required - true if this CollectionParameter is required, false otherwise

datatype - the data type of the parameters in the collection

errorMessage - the error message of the last error or null

rangeable - true if the current instance is rangeable

CollectionParameter

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

Constructor for a CollectionParameter.

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 CollectionParameter is required, false otherwise

Throws:

CollectionParameter.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:

CollectionParameter(DataType, String[], Object[], String[], String, String, boolean)

CollectionParameter

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

Constructor for a CollectionParameter.

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 CollectionParameter is required, false otherwise

Throws:

CollectionParameter.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[])

CollectionParameter

public CollectionParameter(ParameterSet[] values,
                           String[] keys,
                           String[] comments,
                           String name,
                           String comment,
                           boolean required)

Constructor for a CollectionParameter from an array of ParameterSets. This constructor can be used to easily construct a CollectionParameter 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

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

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[])

CollectionParameter

public CollectionParameter(InstanceParameterSet[] values,
                           String name,
                           String comment,
                           boolean required)

Constructor for a CollectionParameter from an array of ParameterSets. This constructor can be used to easily construct a CollectionParameter 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[])

CollectionParameter

public CollectionParameter(StringBuffer representation)
                    throws NonParsableException

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

Parameters:

representation - the XML representation as StringBuffer

Throws:

NonParsableException - if the StringBuffer representation could not be parsed

See Also:

fromXML(StringBuffer)

Method Detail

clone

public CollectionParameter clone()
                          throws CloneNotSupportedException

Overrides:

clone in class Parameter

Throws:

CloneNotSupportedException

createParameterSet

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

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

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 boolean hasDefault()

Returns true, if this CollectionParameter has a default value.

Returns:

if this CollectionParameter has a default value

See Also:

CollectionParameter(ParameterSet, int, int, boolean, String, String, boolean, DataType, String, boolean), setDefault(Object)

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

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

checkValue

public boolean checkValue(Object value)

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

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 CollectionParameter, 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

toXML

public StringBuffer toXML()

Description copied from interface: Storable

This method returns an XML representation as StringBuffer of an instance of the implementing class.

Specified by:

toXML in interface Storable

Overrides:

toXML in class Parameter

Returns:

the XML representation

appendCollection

protected void appendCollection(StringBuffer buf)

Appends the internal ParameterSet in its XML representation ( ParameterSet.toXML()) to the StringBuffer buf.

Parameters:

buf - the StringBuffer this method appends to

fromXML

protected void fromXML(StringBuffer representation)
                throws NonParsableException

Description copied from class: Parameter

Parses a Parameter from a XML representation as returned by Parameter.toXML().

Overrides:

fromXML in class Parameter

Parameters:

representation - the XML representation as StringBuffer

Throws:

NonParsableException - if the XML code could not be parsed

See Also:

Parameter.toXML()

extractCollection

protected void extractCollection(StringBuffer buf)
                          throws NonParsableException

Extracts the internal ParameterSet from its XML representation ( ParameterSet.toXML()). Reverse method to appendCollection(StringBuffer).

Parameters:

buf - the StringBuffer containing the XML representation

Throws:

NonParsableException - if the XML code could not be parsed

getName

public String getName()

Description copied from class: Parameter

Returns the name of the Parameter.

Specified by:

getName in class Parameter

Returns:

the name of the Parameter

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

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:

true if the Parameter is required, false otherwise

isSelected

public 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

getSelected

public int getSelected()

Returns the index of the selected value.

Returns:

the index of the selected value

getDefault

protected int getDefault()

Returns the index of the default selected value.

Returns:

the index of the default selected value

isUserSelected

public boolean isUserSelected()

Returns true if the value was selected by the user.

Returns:

true if the value was selected by the user.

setValue

public void setValue(Object value)
              throws SimpleParameter.IllegalValueException

Sets the selected value to the one that is specified by the key value.

Specified by:

setValue in class Parameter

Parameters:

value - the key of the desired value

Throws:

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

setDefault

public void setDefault(Object defaultValue)
                throws SimpleParameter.IllegalValueException

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:

SimpleParameter.IllegalValueException

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 no defaults are given.

Specified by:

reset in class Parameter

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

equals

public boolean equals(Object o2)

Overrides:

equals in class Object

getRangedInstance

public Parameter 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

toString

public String toString()

Overrides:

toString in class Object

toGalaxy

public void toGalaxy(String namePrefix,
                     String configPrefix,
                     int depth,
                     StringBuffer descBuffer,
                     StringBuffer configBuffer)
              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 configuation 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

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