de.jstacs.parameters
Class ParameterSet

java.lang.Object
  extended by de.jstacs.parameters.ParameterSet
All Implemented Interfaces:
RangeIterator, Storable, Cloneable
Direct Known Subclasses:
Alphabet.AlphabetParameterSet, AlphabetContainerParameterSet, ClassifierAssessmentAssessParameterSet, ExpandableParameterSet, InstanceParameterSet, SimpleParameterSet

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

(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 ParameterSets 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  Class alternativeInstanceClass
          The class that can be instantiated using this ParameterSet
protected  String errorMessage
          The error-message of the last error or null
protected  ParameterSet.ParameterList parameters
          The set of parameters
protected  ParameterSetContainer parent
          Is 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.
  ParameterSet(Class alternativeInstanceClass)
          Constructs a ParameterSet from the class that can be instantiated using this ParameterSet.
protected ParameterSet(Parameter[] parameters)
          Constructs a ParameterSet out of an array of parameters.
  ParameterSet(StringBuffer representation)
          Constructs a ParameterSet out of an XML representation
 
Method Summary
 ParameterSet clone()
          Creates a full clone (deep copy) of this ParameterSet.
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.
 InstantiableFromParameterSet getInstance()
          Returns a new instance of the class of getInstanceClass() that was created using this ParameterSet.
 Class getInstanceClass()
          Returns the class of the instances that can be constructed using this set.
abstract  String getInstanceComment()
          Returns a comment (a textual description) of the class that can be constructed using this ParameterSet.
abstract  String getInstanceName()
          Returns the name of an instance of the class that can be constructed using this ParameterSet.
 int getNumberOfParameters()
          Returns the number of parameters in set
 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 range iterator 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 the loadParameters()-method
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 setAlternativeInstanceClass(Class c)
          Sets the class of the instances that can be constructed using this set.
 void setParent(ParameterSetContainer parent)
          Sets the enclosing ParameterSetContainer of this ParameterSet to parent.
 void simplify()
          Simplifies all parameters in this ParameterSet
 StringBuffer toXML()
          This method returns an XML-representation 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


alternativeInstanceClass

protected Class alternativeInstanceClass
The class that can be instantiated using this ParameterSet


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
Is this ParameterSet is contained in a ParameterSetContainer, this variable holds a reference to that ParameterSetContainer.

Constructor Detail

ParameterSet

public ParameterSet(Class alternativeInstanceClass)
Constructs a ParameterSet from the class that can be instantiated using this ParameterSet. The set of parameters is loaded by the loadParameters()-method if this ParameterSet is expected to be filled with values.

Parameters:
alternativeInstanceClass - the class

ParameterSet

public ParameterSet()
             throws UnsupportedOperationException
Constructs a new ParameterSet with empty parameter values. The set of parameters is loaded by the loadParameters()-method.
This constructor should only be used to create "filled" ParameterSets, i.e. to create ParameterSets from a set of values and not to fill it from the platform user-interface. If this constructor is used as the super-contructor for constructors that shall be used in the platform user-interface, the lazy evaluation of loadParameters()-methods will be lost and memory may probably be wasted.

Throws:
UnsupportedOperationException - if the ParameterSet could not be constructed or the parameters could not be loaded an UnsupportedOperationException is thrown.

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
Constructs a ParameterSet out of an XML representation

Parameters:
representation - the XML representation
Throws:
NonParsableException - if the ParameterSet could not be reconstructed out of the representation, a NonParsableException is thrown
Method Detail

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 fulfils the conventions of Object's method clone()

Overrides:
clone in class Object
Returns:
a deep clone 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 simply creating a new ArrayList<Parameter> for the field parameters/code> and filling it with instances of subclasses of Parameter

Throws:
Exception - an Exception is thrown if the parameters could not be loaded
See Also:
parameters, Parameter

getInstanceName

public abstract String getInstanceName()
Returns the name of an instance of the class that can be constructed using this ParameterSet.

Returns:
the name

getInstanceComment

public abstract String getInstanceComment()
Returns a comment (a textual description) of the class that can be constructed using this ParameterSet.

Returns:
the comment

parametersLoaded

public boolean parametersLoaded()
Returns true if the parameters of this ParameterSet have already been loaded using the loadParameters()-method

Returns:
the state of the parameters

setAlternativeInstanceClass

public void setAlternativeInstanceClass(Class c)
Sets the class of the instances that can be constructed using this set.

Parameters:
c - the class

getInstanceClass

public Class getInstanceClass()
Returns the class of the instances that can be constructed using this set.

Returns:
the class

isAtomic

public boolean isAtomic()
Returns true if this ParameterSet contains only atomic parameters, i.e. the parameters do not contain ParameterSets themselves.

Returns:
if atomic

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 specifiy some ParameterValidator on these parameters or implement these contraints 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

getErrorMessage

public String getErrorMessage()
Returns the message of the last error that occurred. If no error occurred this method returns null.

Returns:
the message

getNumberOfParameters

public int getNumberOfParameters()
Returns the number of parameters in set

Returns:
the number of parameters

getParameterAt

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

Parameters:
i - the position
Returns:
the parameter

makeRanged

public void makeRanged()
                throws Exception
Replaces all Parameters in this ParameterSet by their equivalents implementing the Rangeable interface.

Throws:
Exception - is thrown if these instances could not be created

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:
if the next element exists
Throws:
ParameterException - if the next value could not be set

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 range iterator is ranging over a set of values.

Specified by:
isRanged in interface RangeIterator
Returns:
if ranging

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 representation

replaceParametersWithRangedInstance

protected void replaceParametersWithRangedInstance()
                                            throws Exception
Replaces all Parameters in this ParameterSet by their equivalents implementing the Rangeable interface.

Throws:
Exception - is thrown if these instances could not be created

getInstance

public InstantiableFromParameterSet getInstance()
                                         throws ParameterSetParser.NotInstantiableException
Returns a new instance of the class of getInstanceClass() that was created using this ParameterSet.

Returns:
the instance
Throws:
ParameterSetParser.NotInstantiableException - is thrown if the class could not be instantiated
See Also:
ParameterSetParser

toXML

public StringBuffer toXML()
Description copied from interface: Storable
This method returns an XML-representation 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
Throws:
NonParsableException - is thrown if the XML-code could not be parsed

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

getParent

public ParameterSetContainer getParent()
Returns the enclosing ParameterSetContainer of this ParameterSet or null if none exists.

Returns:
the parent

setParent

public void setParent(ParameterSetContainer parent)
Sets the enclosing ParameterSetContainer of this ParameterSet to parent.

Parameters:
parent - the new parent