de.jstacs.parameters
Class CollectionParameter

java.lang.Object
  extended by de.jstacs.parameters.Parameter
      extended by de.jstacs.parameters.CollectionParameter
All Implemented Interfaces:
Rangeable, Storable, Cloneable
Direct Known Subclasses:
EnumParameter, MultiSelectionCollectionParameter

public class CollectionParameter
extends Parameter
implements Rangeable

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(ParameterSet[] values, 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)
          Restores an instance of CollectionParameter from a string representation
 
Method Summary
protected  void appendCollection(StringBuffer buf)
          Appends the internal ParameterSet in its XML-representation (ParameterSet.toXML()) to 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()).
protected  void fromXML(StringBuffer representation)
          Parses a Parameter from an 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 all the parameters in this collection are either set by the user or have default values
 boolean isAtomic()
          Returns true if the collection is of an atomic data type
 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 isSet()
          Returns true if this collection parameter was selected by the user.
 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 not 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.
 StringBuffer toXML()
          This method returns an XML-representation 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, toString, 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 is the current value was selected by the user
name - the name
comment - the comment
required - true if this CollectionParameter is required
datatype - the datatype of this CollectionParameter
errorMessage - the error-message of the last error or null
rangeable - 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 the 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 the parameter is required, false otherwise
Throws:
CollectionParameter.InconsistentCollectionException - if the length of the keys and the values is different or the collection is inconsistent for some other reason, an InconsistentCollectionExceptionSimpleParameter.IllegalValueException - if one of the values in values is not of type datatype, an IllegalValueException is thrown
SimpleParameter.DatatypeNotValidException - is thrown if the datatype is not one of the allowed values

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 the 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 parameter is required, false otherwise
Throws:
CollectionParameter.InconsistentCollectionException - if the length of the keys and the values is different or the collection is inconsistent for some other reason, an InconsistentCollectionExceptionSimpleParameter.IllegalValueException - if one of the values in values is not of type datatype, an IllegalValueException is thrown
SimpleParameter.DatatypeNotValidException

CollectionParameter

public CollectionParameter(ParameterSet[] 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

CollectionParameter

public CollectionParameter(StringBuffer representation)
                    throws NonParsableException
Restores an instance of CollectionParameter from a string representation

Parameters:
representation - the string representation
Throws:
NonParsableException - if the representation could not be parsed to a CollectionParameter, a NonParsableException is thrown
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 the 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, an IllegalValueException is thrown
SimpleParameter.DatatypeNotValidException - is thrown 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()
Returns true if the collection is of an atomic data type

Specified by:
isAtomic in class Parameter
Returns:
if the parameter is atomic

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()
Returns true if all the parameters in this collection are either set by the user or have default values

Specified by:
hasDefaultOrIsSet in class Parameter
Returns:
if value has default or is set

isSet

public boolean isSet()
Returns true if this collection parameter was selected by the user.

Specified by:
isSet in class Parameter
Returns:
if the parameter was set

getParametersInCollection

public ParameterSet getParametersInCollection()
Returns the possible values in this collection

Returns:
the values/parameters

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:
if the parameter can be varied

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 or false

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:
the error message

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
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 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 an XML-representation as returned by Parameter.toXML().

Overrides:
fromXML in class Parameter
Parameters:
representation - the XML-representation
Throws:
NonParsableException - is thrown if the XML-code could not be parsed

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 - is thrown 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

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

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:
if the parameter is required

getSelected

public int getSelected()
Returns the index of the selected value.

Returns:
the index

getDefault

protected int getDefault()
Returns the index of the default selected value.

Returns:
the index

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 an IllegalValueException is thrown

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

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:
the instance
Throws:
Exception - is thrown if isRangeable() returns false or the ranged instance could not be created for some other reason