de.jstacs.parameters
Class ParameterSet

java.lang.Object
  de.jstacs.parameters.ParameterSet

All Implemented Interfaces:

GalaxyConvertible, RangeIterator, Storable, Cloneable

Direct Known Subclasses:

ClassifierAssessmentAssessParameterSet, ExpandableParameterSet, HMMTrainingParameterSet, InstanceParameterSet, SimpleParameterSet

public abstract class ParameterSet
extends Object
implements Storable, Cloneable, RangeIterator, GalaxyConvertible

(Container) class for a set of Parameters. This is the base class for other ParameterSets that provide more specialized methods, e.g. for expanding the set of Parameters at runtime ( ExpandableParameterSet ) or defining an array of ParameterSet s from a common template ( ArrayParameterSet ).

Author:

Jan Grau

Nested Class Summary

class

ParameterSet.ParameterList Class for a List of Parameters that basically has the same functionality as ArrayList, but additionally takes care of the references Parameter.parent.

Field Summary

protected String	errorMessage The error message of the last error or null
protected ParameterSet.ParameterList	parameters The set of parameters
protected ParameterSetContainer	parent If this ParameterSet is contained in a ParameterSetContainer, this variable holds a reference to that ParameterSetContainer.
protected boolean	ranged Indicates if the Parameters of this ParameterSet that implement Rangeable and return true shall be replaced by their ranged instances

Constructor Summary

	ParameterSet() Constructs a new ParameterSet with empty parameter values.
protected	ParameterSet(ArrayList<Parameter> parameters) Constructs a ParameterSet out of an ArrayList of Parameters.
protected	ParameterSet(Parameter[] parameters) Constructs a ParameterSet out of an array of Parameters.
	ParameterSet(StringBuffer representation) The standard constructor for the interface Storable.

Method Summary

ParameterSet	clone() Creates a full clone (deep copy) of this ParameterSet.
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 the instance fields of a ParameterSet from the XML representation as returned by toXML().
String	getErrorMessage() Returns the message of the last error that occurred.
long	getId() Returns the id of this ParameterSet.
static int	getIndex(String[] names, Object[] values, Comparable current, boolean hasAlternative) This method tries to find the correct name (String) for your choice.
int	getNumberOfParameters() Returns the number of parameters in the ParameterSet.
int	getNumberOfValues() Returns the number of values in the collection.
Parameter	getParameterAt(int i) Returns the Parameter at position i.
ParameterSetContainer	getParent() Returns the enclosing ParameterSetContainer of this ParameterSet or null if none exists.
boolean	hasDefaultOrIsSet() Returns true if all parameters in this ParameterSet are either set by the user or have default values.
protected void	initParameterList() Initializes the internal set of Parameters, which is a ParameterSet.ParameterList.
protected void	initParameterList(int initCapacity) Initializes the internal set of Parameters, which is a ParameterSet.ParameterList, with an initial number of Parameters of initCapacity.
boolean	isAtomic() Returns true if this ParameterSet contains only atomic parameters, i.e. the parameters do not contain ParameterSets themselves.
boolean	isRanged() Returns true if this RangeIterator is ranging over a set of values.
protected abstract void	loadParameters() Loads the parameters for this ParameterSet.
void	makeRanged() Replaces all Parameters in this ParameterSet by their equivalents implementing the Rangeable interface.
boolean	next() Switches to the next value in the collection of values in the specified range.
boolean	parametersLoaded() Returns true if the parameters of this ParameterSet have already been loaded using loadParameters().
protected void	propagateId() Propagates the id of this ParameterSet to all Parameters above and below in the hierarchy.
protected void	recieveId() Searches for all Parameter.neededReferenceIds in the hierarchy below this ParameterSet and sets the corresponding Parameter.neededReferences.
protected void	replaceParametersWithRangedInstance() Replaces all Parameters in this ParameterSet by their equivalents implementing the Rangeable interface.
void	reset() Resets all Parameters in this ParameterSet to their default values or null if not default value was provided.
void	resetToFirst() Resets the current value in the collection to the first value.
void	setParent(ParameterSetContainer parent) Sets the enclosing ParameterSetContainer of this ParameterSet to parent.
void	simplify() Simplifies all Parameters in this ParameterSet.
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.
StringBuffer	toXML() This method returns an XML representation as StringBuffer of an instance of the implementing class.
String	valuesToString() Returns a String representation of the set of values.

Methods inherited from class java.lang.Object

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

Field Detail

parameters

protected ParameterSet.ParameterList parameters

The set of parameters

errorMessage

protected String errorMessage

The error message of the last error or null

ranged

protected boolean ranged

Indicates if the Parameters of this ParameterSet that implement Rangeable and return true shall be replaced by their ranged instances

parent

protected ParameterSetContainer parent

If this ParameterSet is contained in a ParameterSetContainer, this variable holds a reference to that ParameterSetContainer.

Constructor Detail

ParameterSet

public ParameterSet()

Constructs a new ParameterSet with empty parameter values. The set of parameters is loaded by the method loadParameters() as soon as one of the accession methods, e.g. getNumberOfParameters(), is called.

ParameterSet

protected ParameterSet(Parameter[] parameters)

Constructs a ParameterSet out of an array of Parameters. The Parameters are not cloned, but passed by reference.

Parameters:

parameters - the Parameters

ParameterSet

protected ParameterSet(ArrayList<Parameter> parameters)

Constructs a ParameterSet out of an ArrayList of Parameters. The Parameters are not cloned, but passed by reference.

Parameters:

parameters - the Parameters

ParameterSet

public ParameterSet(StringBuffer representation)
             throws NonParsableException

The standard constructor for the interface Storable. Constructs a ParameterSet out of an XML representation.

Parameters:

representation - the XML representation as StringBuffer

Throws:

NonParsableException - if the ParameterSet could not be reconstructed out of the StringBuffer representation

Method Detail

getIndex

public static int getIndex(String[] names,
                           Object[] values,
                           Comparable current,
                           boolean hasAlternative)
                    throws IllegalArgumentException

This method tries to find the correct name (String) for your choice. This method is useful if you handle CollectionParameters.

Parameters:

names - the names

values - the values that can be set

current - the value to be set

hasAlternative - indicates whether the last entry of names is an alternative parameter

Returns:

the StringIndexOutOfBoundsException that has to be used

Throws:

IllegalArgumentException - if no match could be found

See Also:

CollectionParameter

clone

public ParameterSet clone()
                   throws CloneNotSupportedException

Creates a full clone (deep copy) of this ParameterSet. As a convenience-method the user can use fillWithStandardFieldsForClone(ParameterSet) on a newly created instance of a subclass of ParameterSet to obtain a clone/copy of all standard member variables (those already defined in ParameterSet) in the passed ParameterSet. Using this method, the cloning process becomes merely three-step:

• Create a new instance of your subclass of ParameterSet, most likely with an empty constructor or the one taking just the instance class.
• Call this.fillWithStandardFieldsForClone on this instance.
• Return the instance.

This method fulfills the conventions of Object's method Object.clone().

Overrides:

clone in class Object

Returns:

a deep clone/copy of this ParameterSet

Throws:

CloneNotSupportedException

initParameterList

protected final void initParameterList()

Initializes the internal set of Parameters, which is a ParameterSet.ParameterList.

initParameterList

protected final void initParameterList(int initCapacity)

Initializes the internal set of Parameters, which is a ParameterSet.ParameterList, with an initial number of Parameters of initCapacity.

Parameters:

initCapacity - the initial number of Parameters

loadParameters

protected abstract void loadParameters()
                                throws Exception

Loads the parameters for this ParameterSet. This is in most cases done by calling initParameterList() or initParameterList(int) to initialize parameters and afterwards filling parameters with instances of subclasses of Parameter.

Throws:

Exception - if the parameters could not be loaded

See Also:

Parameter, parameters, initParameterList(), initParameterList(int)

parametersLoaded

public boolean parametersLoaded()

Returns true if the parameters of this ParameterSet have already been loaded using loadParameters().

Returns:

the state of the parameters (loaded or not)

isAtomic

public boolean isAtomic()

Returns true if this ParameterSet contains only atomic parameters, i.e. the parameters do not contain ParameterSets themselves.

Returns:

true if the ParameterSet contains only atomic parameters, false otherwise

hasDefaultOrIsSet

public boolean hasDefaultOrIsSet()

Returns true if all parameters in this ParameterSet are either set by the user or have default values. If any additional constraints are required on your parameters you should either specify some ParameterValidator on these parameters or implement these constraints by overriding this method in your implementation of ParameterSet. It is recommended to specify a useful remark which constraint failed in the member-variable errorMessage, which will be displayed to the user. In the overriding method super.hasDefaultOrIsSet() should be called prior to checking specific constraints.

Returns:

true if all parameters have some allowed value set, false otherwise

getErrorMessage

public String getErrorMessage()

Returns the message of the last error that occurred. If no error occurred this method returns null.

Returns:

the error message of the last error or null

getNumberOfParameters

public int getNumberOfParameters()

Returns the number of parameters in the ParameterSet.

Returns:

the number of parameters in the ParameterSet

getParameterAt

public Parameter getParameterAt(int i)

Returns the Parameter at position i.

Parameters:

i - the position in the ParameterSet.ParameterList

Returns:

the Parameter at position i

makeRanged

public void makeRanged()
                throws Exception

Replaces all Parameters in this ParameterSet by their equivalents implementing the Rangeable interface.

Throws:

Exception - if these instances could not be created

See Also:

replaceParametersWithRangedInstance()

next

public boolean next()
             throws ParameterException

Description copied from interface: RangeIterator

Switches to the next value in the collection of values in the specified range.

Specified by:

next in interface RangeIterator

Returns:

true if the next element exists, false otherwise

Throws:

ParameterException - if the next value could not be fetched

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

getNumberOfValues

public int getNumberOfValues()

Description copied from interface: RangeIterator

Returns the number of values in the collection.

Specified by:

getNumberOfValues in interface RangeIterator

Returns:

the number of values

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

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

replaceParametersWithRangedInstance

protected void replaceParametersWithRangedInstance()
                                            throws Exception

Replaces all Parameters in this ParameterSet by their equivalents implementing the Rangeable interface.

Throws:

Exception - if these instances could not be created

See Also:

makeRanged()

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

Returns:

the XML representation

simplify

public void simplify()

Simplifies all Parameters in this ParameterSet.

See Also:

Parameter.simplify()

reset

public void reset()

Resets all Parameters in this ParameterSet to their default values or null if not default value was provided.

See Also:

Parameter.reset()

fromXML

protected void fromXML(StringBuffer representation)
                throws NonParsableException

Parses the instance fields of a ParameterSet from the XML representation as returned by toXML().

Parameters:

representation - the XML representation as StringBuffer

Throws:

NonParsableException - if the XML code could not be parsed

See Also:

toXML()

recieveId

protected void recieveId()

Searches for all Parameter.neededReferenceIds in the hierarchy below this ParameterSet and sets the corresponding Parameter.neededReferences.

propagateId

protected void propagateId()

Propagates the id of this ParameterSet to all Parameters above and below in the hierarchy.

getId

public long getId()

Returns the id of this ParameterSet.

Returns:

the id of the ParameterSet

getParent

public ParameterSetContainer getParent()

Returns the enclosing ParameterSetContainer of this ParameterSet or null if none exists.

Returns:

the enclosing ParameterSetContainer (parent)

setParent

public void setParent(ParameterSetContainer parent)

Sets the enclosing ParameterSetContainer of this ParameterSet to parent.

Parameters:

parent - the new parent

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