org.opensha.commons.param.impl
Class WarningIntegerParameter

java.lang.Object
  org.opensha.commons.param.AbstractParameter<Integer>
      org.opensha.commons.param.impl.IntegerParameter
          org.opensha.commons.param.impl.WarningIntegerParameter

All Implemented Interfaces:

Serializable, Comparable<Parameter<?>>, Named, XMLSaveable, Parameter<Integer>, WarningParameter<Integer>

public class WarningIntegerParameter
extends IntegerParameter
implements WarningParameter<Integer>

Title: WarningIntegerParameter

Description: Concrete implementation of the WarningParameterAPI interface that stores a Integer for it's value object. Maintains a list of listeners and passes them ParameterChangeWarningEvents when the value is attemted to be set beyong the warning constraints.

Typical use case is that there is one listener that also acts as the editor of the value, ( such as the GUI component attempting to update the value ). This listener attempts to change the value outside the warning range. The listener is notified of the attemp, i.e. "warned". This listener then notifies the user via a DialogBox. The user is then given the option to cancel or ignore the warning and set the value. The listener will then set the value ignoring the warning.

The whole reason for using a listener is that any type of situation can be handled. This class doesn't need to know anything about the listener other than it adheres to the ParameterChangeWarningListener interface. The listener can be any class, and can be updated to any new class in the future. This class never has to be changed. This means that this parameter component is not tied to any specific class of editors, a guiding principle in object-oriented programming.

Note: All listeners must implement the ParameterChangeFailListener interface.

Note: Since this class extends from IntegerParameter it also has a second absolute IntegerConstraint that can never be exceeded. It's important that the programmer realizes this and ensures the warning constraints are smaller than the absolute constraints when using this parameter in their program.

Version:

1.0

Author:

Steven W. Rock

See Also:

ParameterChangeWarningListener, ParameterChangeWarningEvent, Serialized Form

Field Summary

protected static String	C Class name for debugging.
protected static boolean	D If true print out debug statements.
protected IntegerConstraint	warningConstraint The constraint for this Parameter.
protected ArrayList	warningListeners A list of listeners to receive warning events.

Fields inherited from class org.opensha.commons.param.AbstractParameter

constraint, defaultValue, editable, independentParameters, info, metadataString, name, units, value, XML_COMPLEX_VAL_EL_NAME, XML_GROUP_METADATA_NAME, XML_METADATA_NAME, XML_NULL_VALUE

Fields inherited from interface org.opensha.commons.param.Parameter

XML_INDEPENDENT_PARAMS_NAME

Fields inherited from interface org.opensha.commons.metadata.XMLSaveable

XML_METADATA_NAME

Constructor Summary

WarningIntegerParameter(String name)
No warning constraints or absolute constraints specified.

WarningIntegerParameter(String name, Integer value)
No constraints specified, all values allowed.

WarningIntegerParameter(String name, IntegerConstraint constraint)
Sets the name and Constraints object.

WarningIntegerParameter(String name, IntegerConstraint constraint, Integer value)
Sets the name, value and constraint.

WarningIntegerParameter(String name, IntegerConstraint constraint, String units)
Sets the name, constraints, and sets the units.

WarningIntegerParameter(String name, IntegerConstraint constraint, String units, Integer value)
This is the main constructor.

WarningIntegerParameter(String name, Integer min, Integer max)
Sets the name, defines the constraints min and max values.

WarningIntegerParameter(String name, Integer min, Integer max, String units)
Sets the name, defines the constraints min and max values, and sets the units.

WarningIntegerParameter(String name, Integer min, Integer max, String units, Integer value)
Sets all values, and the constraint is created from the min and max values.

WarningIntegerParameter(String name, int min, int max)
Sets the name, defines the constraints min and max values.

WarningIntegerParameter(String name, int min, int max, Integer value)
Sets the name, and value.

WarningIntegerParameter(String name, int min, int max, String units)
Sets the name, defines the constraints min and max values, and sets the units.

WarningIntegerParameter(String name, int min, int max, String units, Integer value)
Sets all values, and the constraint is created from the min and max values.

WarningIntegerParameter(String name, String units)
No warning constraints or absolute constraints specified.

WarningIntegerParameter(String name, String units, Integer value)
Sets the name, units and value.

Method Summary

void	addParameterChangeWarningListener(ParameterChangeWarningListener listener) Adds a ParameterChangeFailListener to the list of listeners.
Object	clone() Returns a copy so you can't edit or damage the origial.
void	fireParameterChangeWarning(ParameterChangeWarningEvent event) This is the function that notifies all listeners assigned to this parameter that the warning constraints have been exceeded.
AbstractParameterConstraint	getWarningConstraint() Replaces the warning constraints with a new constraint object.
Integer	getWarningMax() Proxy passthrough method to the IntegerConstraint to get the minimumn value below which warnings will be issued.
Integer	getWarningMin() Proxy passthrough method to the IntegerConstraint to get the minimumn value below which warnings will be issued.
boolean	isIgnoreWarning() Returns warning constraint enabled/disabled.
boolean	isRecommended(Integer obj) Uses the warning constraint object to determine if the new value being set is within recommended range.
void	removeParameterChangeWarningListener(ParameterChangeWarningListener listener) Removes a ParameterChangeFailListener to the list of listeners.
void	setIgnoreWarning(boolean ignoreWarning) Set to true to turn off warnings, will automatically set the value, unless exceeds Absolute contrsints.
void	setValue(Integer value) Attempts to update the value of this parameter with a new Integer.
void	setValueIgnoreWarning(Integer value) Attempts to update the value of this parameter with a new Integer.
void	setWarningConstraint(AbstractParameterConstraint warningConstraint) Replaces the warning constraints with a new constraint object.

Methods inherited from class org.opensha.commons.param.impl.IntegerParameter

getEditor, getMax, getMin, getType, isAllowed, setConstraint, setIndividualParamValueFromXML

Methods inherited from class org.opensha.commons.param.AbstractParameter

addIndependentParameter, addParameterChangeFailListener, addParameterChangeListener, checkEditable, compareTo, containsIndependentParameter, equals, firePropertyChange, firePropertyChangeFailed, getConstraint, getConstraintName, getDefaultValue, getDependentParamMetadataString, getIndependentParameter, getIndependentParameterList, getIndependentParametersIterator, getIndependentParametersKey, getInfo, getMetadataString, getName, getNumIndependentParameters, getUnits, getValue, isAllowed, isEditable, isNullAllowed, removeIndependentParameter, removeParameterChangeFailListener, removeParameterChangeListener, setDefaultValue, setDependentParamMetadataString, setIndependentParameters, setIndepParamsFromXML, setInfo, setName, setNonEditable, setUnits, setValueAsDefault, setValueFromXMLMetadata, toXMLMetadata, toXMLMetadata, unableToSetValue, valueToXML

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.opensha.commons.param.WarningParameter

equals

Methods inherited from interface org.opensha.commons.param.Parameter

addIndependentParameter, addParameterChangeFailListener, addParameterChangeListener, containsIndependentParameter, firePropertyChange, firePropertyChangeFailed, getConstraint, getConstraintName, getDefaultValue, getDependentParamMetadataString, getEditor, getIndependentParameter, getIndependentParametersIterator, getIndependentParametersKey, getInfo, getMetadataString, getNumIndependentParameters, getType, getUnits, getValue, isAllowed, isEditable, isNullAllowed, removeIndependentParameter, removeParameterChangeFailListener, removeParameterChangeListener, setConstraint, setDefaultValue, setIndependentParameters, setInfo, setName, setNonEditable, setUnits, setValueAsDefault, setValueFromXMLMetadata, toXMLMetadata, unableToSetValue

Methods inherited from interface org.opensha.commons.data.Named

getName

Methods inherited from interface java.lang.Comparable

compareTo

Methods inherited from interface org.opensha.commons.metadata.XMLSaveable

toXMLMetadata

Field Detail

C

protected static final String C

Class name for debugging.

See Also:

Constant Field Values

D

protected static final boolean D

If true print out debug statements.

See Also:

Constant Field Values

warningConstraint

protected IntegerConstraint warningConstraint

The constraint for this Parameter.

warningListeners

protected transient ArrayList warningListeners

A list of listeners to receive warning events. Only created if needed, else kept null. This is known as "lazy instantiation".

Constructor Detail

WarningIntegerParameter

public WarningIntegerParameter(String name)

No warning constraints or absolute constraints specified. All values allowed. Also sets the name of this parameter.

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               String units)

No warning constraints or absolute constraints specified. All values allowed. Also sets the name and units of this parameter.

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               int min,
                               int max)
                        throws ConstraintException

Sets the name, defines the constraints min and max values. Creates the constraint object from these values.

Parameters:

name - Name of the parameter

min - defines min of allowed values

max - defines max of allowed values

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               int min,
                               int max,
                               String units)
                        throws ConstraintException

Sets the name, defines the constraints min and max values, and sets the units. Creates the constraint object from these values.

Parameters:

name - Name of the parameter

min - defines min of allowed values

max - defines max of allowed values

units - Units of this parameter

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               Integer min,
                               Integer max)
                        throws ConstraintException

Sets the name, defines the constraints min and max values. Creates the constraint object from these values.

Parameters:

name - Name of the parameter

min - defines min of allowed values

max - defines max of allowed values

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               Integer min,
                               Integer max,
                               String units)
                        throws ConstraintException

Sets the name, defines the constraints min and max values, and sets the units. Creates the constraint object from these values.

Parameters:

name - Name of the parameter

min - defines min of allowed values

max - defines max of allowed values

units - Units of this parameter

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               IntegerConstraint constraint)
                        throws ConstraintException

Sets the name and Constraints object.

Parameters:

name - Name of the parameter

constraint - defines min and max range of allowed values

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               IntegerConstraint constraint,
                               String units)
                        throws ConstraintException

Sets the name, constraints, and sets the units.

Parameters:

name - Name of the parameter

constraint - defines min and max range of allowed values

units - Units of this parameter

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowedallowed one. Null values are always allowed in the constructors

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               Integer value)

No constraints specified, all values allowed. Sets the name and value.

Parameters:

name - Name of the parameter

value - Integer value of this parameter

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               String units,
                               Integer value)
                        throws ConstraintException

Sets the name, units and value. All values allowed because constraints. not set.

Parameters:

name - Name of the parameter

value - Integer value of this parameter

units - Units of this parameter

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               int min,
                               int max,
                               Integer value)
                        throws ConstraintException

Sets the name, and value. Also defines the min and max from which the constraint is constructed.

Parameters:

name - Name of the parameter

value - Integer value of this parameter

min - defines max of allowed values

max - defines min of allowed values

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               IntegerConstraint constraint,
                               Integer value)
                        throws ConstraintException

Sets the name, value and constraint. The value is checked if it is within constraints.

Parameters:

name - Name of the parameter

constraint - defines min and max range of allowed values

value - Integer value of this parameter

Throws:

ConstraintException - thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               int min,
                               int max,
                               String units,
                               Integer value)
                        throws ConstraintException

Sets all values, and the constraint is created from the min and max values. The value is checked if it is within constraints.

Parameters:

name - Name of the parameter

value - Integer value of this parameter

min - defines min of allowed values

max - defines max of allowed values

units - Units of this parameter

Throws:

ConstraintException - Is thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               Integer min,
                               Integer max,
                               String units,
                               Integer value)
                        throws ConstraintException

Sets all values, and the constraint is created from the min and max values. The value is checked if it is within constraints.

Parameters:

name - Name of the parameter

value - Integer value of this parameter

min - defines min of allowed values

max - defines max of allowed values

units - Units of this parameter

Throws:

ConstraintException - Is thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

WarningIntegerParameter

public WarningIntegerParameter(String name,
                               IntegerConstraint constraint,
                               String units,
                               Integer value)
                        throws ConstraintException

This is the main constructor. All other constructors call this one. Constraints must be set first, because the value may not be an allowed one. Null values are always allowed in the constructor. If the constraints are null, all values are allowed.

Parameters:

name - Name of the parameter

constraint - defines min and max range of allowed values

value - Integer value of this parameter

units - Units of this parameter

Throws:

ConstraintException - Is thrown if the value is not allowed

ConstraintException - Is thrown if the value is not allowed

Method Detail

addParameterChangeWarningListener

public void addParameterChangeWarningListener(ParameterChangeWarningListener listener)
                                       throws EditableException

Adds a ParameterChangeFailListener to the list of listeners. This is the interface all listeners must implement in order to fit into this framework. This is where the listener list is created if null, i.e. "lazy instantiation".

Specified by:

addParameterChangeWarningListener in interface WarningParameter<Integer>

Parameters:

listener - The feature to be added to the ParameterChangeFailListener attribute

Throws:

EditableException

removeParameterChangeWarningListener

public void removeParameterChangeWarningListener(ParameterChangeWarningListener listener)
                                          throws EditableException

Removes a ParameterChangeFailListener to the list of listeners. This listener will no longer receive warning events.

Specified by:

removeParameterChangeWarningListener in interface WarningParameter<Integer>

Throws:

EditableException

setWarningConstraint

public void setWarningConstraint(AbstractParameterConstraint warningConstraint)
                          throws ParameterException,
                                 EditableException

Replaces the warning constraints with a new constraint object. If this class is set to non-editable an EditableException is thrown.

Specified by:

setWarningConstraint in interface WarningParameter<Integer>

Throws:

ParameterException

EditableException

getWarningConstraint

public AbstractParameterConstraint getWarningConstraint()
                                                 throws ParameterException

Replaces the warning constraints with a new constraint object. If this class is set to non-editable an EditableException is thrown.

Specified by:

getWarningConstraint in interface WarningParameter<Integer>

Throws:

ParameterException

getWarningMin

public Integer getWarningMin()
                      throws Exception

Proxy passthrough method to the IntegerConstraint to get the minimumn value below which warnings will be issued.

Specified by:

getWarningMin in interface WarningParameter<Integer>

Returns:

The min value

Throws:

Exception - Description of the Exception

getWarningMax

public Integer getWarningMax()

Proxy passthrough method to the IntegerConstraint to get the minimumn value below which warnings will be issued.

Specified by:

getWarningMax in interface WarningParameter<Integer>

Returns:

The min value

Throws:

Exception - Description of the Exception

setValue

public void setValue(Integer value)
              throws ConstraintException,
                     WarningException

Attempts to update the value of this parameter with a new Integer. All constraints are checked. If the value exceeds the warning levels all listeners are notified via fireParameterChangeWarning(). If the ignoreWarning flag is present the warning constraints are bypassed. Another condition checked is if the value is null and null values are allowed.

Specified by:

setValue in interface Parameter<Integer>

Overrides:

setValue in class AbstractParameter<Integer>

Parameters:

value - The new value - must be a Integer

Throws:

ConstraintException - Thrown if the new value is beyond the constraint levels or null values not allowed.

WarningException - Thrown if the new value is beyond the warning levels.

setValueIgnoreWarning

public void setValueIgnoreWarning(Integer value)
                           throws ConstraintException,
                                  ParameterException

Attempts to update the value of this parameter with a new Integer. All constraints are checked. If the value exceeds the warning levels all listeners are notified via fireParameterChangeWarning(). If the ignoreWarning flag is present the warning constraints are bypassed. Another condition checked is if the value is null and null values are allowed.

Specified by:

setValueIgnoreWarning in interface WarningParameter<Integer>

Parameters:

value - The new value - must be a Integer

Throws:

ConstraintException - Thrown if the new value is beyond the constraint levels or null values not allowed.

WarningException - Thrown if the new value is beyond the warning levels.

ParameterException - Thrown if the object is currenlty not editable

isRecommended

public boolean isRecommended(Integer obj)

Uses the warning constraint object to determine if the new value being set is within recommended range. If no Constraints are present all values are recommended. The implied intention is that the warning constraint is more restrictive than the absolute constraints so that if a value passes the warning test, it will also pass the absolute constraint test.

Specified by:

isRecommended in interface WarningParameter<Integer>

Parameters:

obj - Object to check if allowed via constraints

Returns:

True if the value is allowed

fireParameterChangeWarning

public void fireParameterChangeWarning(ParameterChangeWarningEvent event)

This is the function that notifies all listeners assigned to this parameter that the warning constraints have been exceeded.

Specified by:

fireParameterChangeWarning in interface WarningParameter<Integer>

Parameters:

event - The event encapsulating the attempted values passed to each listener.

clone

public Object clone()

Returns a copy so you can't edit or damage the origial. All fields, constraints and the value object are cloned.

Specified by:

clone in interface Parameter<Integer>

Overrides:

clone in class IntegerParameter

Returns:

Exact copy of this object's state

setIgnoreWarning

public void setIgnoreWarning(boolean ignoreWarning)

Set to true to turn off warnings, will automatically set the value, unless exceeds Absolute contrsints. Set to false so that warning constraints are enabled, i.e. throw a WarningConstraintException if exceed recommened warnings.

Specified by:

setIgnoreWarning in interface WarningParameter<Integer>

isIgnoreWarning

public boolean isIgnoreWarning()

Returns warning constraint enabled/disabled. If true warnings are turned off , will automatically set the value, unless exceeds Absolute contrsints. If set to false warning constraints are enabled, i.e. throw a WarningConstraintException if exceed recommened warnings.

Specified by:

isIgnoreWarning in interface WarningParameter<Integer>