de.jstacs.parameters
Class ParameterSet

java.lang.Object
  extended by de.jstacs.parameters.ParameterSet
All Implemented Interfaces:
GalaxyConvertible, Storable, Cloneable
Direct Known Subclasses:
AbstractPerformanceMeasure, ClassifierAssessmentAssessParameterSet, ConstraintParameterSet, ExpandableParameterSet, HMMTrainingParameterSet, InstanceParameterSet, SimpleParameterSet

public abstract class ParameterSet
extends Object
implements Storable, Cloneable, 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, Jens Keilwagen

Nested Class Summary
protected  class ParameterSet.ParameterList
          Class for a AnnotatedEntityList that automatically sets the Parameter.parent field to the enclosing ParameterSet.
 
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.
 
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, boolean) 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[] getAllParameterNames()
          Returns the names of all Parameters in this ParameterSet.
static String getComment(Class<? extends ParameterSet> c)
          Returns a comment for the class.
static String getComment(ParameterSet p)
          Returns a comment for the ParameterSet.
 String getErrorMessage()
          Returns the message of the last error that occurred.
static int getIndex(String[] names, Object[] values, Comparable current, boolean hasAlternative)
          This method tries to find the correct name (String) for your choice.
static String getName(Class<? extends ParameterSet> c)
          Returns a name for the class.
static String getName(ParameterSet p)
          Returns a name for the ParameterSet.
 int getNumberOfParameters()
          Returns the number of parameters in the ParameterSet.
 Parameter getParameterAt(int i)
          Returns the Parameter at position i.
 Parameter getParameterForName(String name)
          Returns the Parameter with name name.
 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.
 boolean isComparable(ParameterSet p)
          This method checks whether the given ParameterSet is comparable to the current instance, i.e.
 boolean parametersLoaded()
          Returns true if the parameters of this ParameterSet have been loaded.
 void reset()
          Resets all Parameters in this ParameterSet to their default values or null if not default value was provided.
 void setParent(ParameterSetContainer parent)
          Sets the enclosing ParameterSetContainer of this ParameterSet to parent.
 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.
 StringBuffer toXML()
          This method returns an XML representation as StringBuffer of an instance of the implementing class.
 
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


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.


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

getName

public static String getName(Class<? extends ParameterSet> c)
Returns a name for the class.

Parameters:
c - the given class.
Returns:
a name for the class.
See Also:
ParameterSetContainer.ParameterSetContainer(Class), AbstractSelectionParameter.AbstractSelectionParameter(String, String, boolean, Class...)

getComment

public static String getComment(Class<? extends ParameterSet> c)
Returns a comment for the class.

Parameters:
c - the given class.
Returns:
a comment for the class.
See Also:
ParameterSetContainer.ParameterSetContainer(Class), AbstractSelectionParameter.AbstractSelectionParameter(String, String, boolean, Class...)

getName

public static String getName(ParameterSet p)
Returns a name for the ParameterSet.

Parameters:
p - the given ParameterSet.
Returns:
a name for the ParameterSet.
See Also:
ParameterSetContainer.ParameterSetContainer(ParameterSet), AbstractSelectionParameter.AbstractSelectionParameter(String, String, boolean, ParameterSet...), getName(Class), Object.getClass()

getComment

public static String getComment(ParameterSet p)
Returns a comment for the ParameterSet.

Parameters:
p - the given ParameterSet.
Returns:
a comment for the ParameterSet.
See Also:
ParameterSetContainer.ParameterSetContainer(ParameterSet), AbstractSelectionParameter.AbstractSelectionParameter(String, String, boolean, ParameterSet...), getComment(Class), Object.getClass()

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 AbstractSelectionParameters.

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:
AbstractSelectionParameter

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

parametersLoaded

public boolean parametersLoaded()
Returns true if the parameters of this ParameterSet have been loaded.

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

getAllParameterNames

public String[] getAllParameterNames()
Returns the names of all Parameters in this ParameterSet.

Returns:
an array containing the names of all Parameters in this ParameterSet

getParameterForName

public Parameter getParameterForName(String name)
Returns the Parameter with name name.

Parameters:
name - the name of the Parameter
Returns:
the Parameter with name name

getParameterAt

public Parameter getParameterAt(int i)
Returns the Parameter at position i.

Parameters:
i - the position in the ParameterSet
Returns:
the Parameter at position i

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

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

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

isComparable

public boolean isComparable(ParameterSet p)
This method checks whether the given ParameterSet is comparable to the current instance, i.e. whether the Class and the number of parameters are identical, and the individual Parameters are comparable. In other words, the method returns true if the ParameterSets only differ in their specific raw values.

Parameters:
p - the ParameterSet for the comparison
Returns:
true if the ParameterSets only differ in their values, otherwise false
See Also:
Object.getClass(), getNumberOfParameters(), Parameter.isComparable(Parameter)