org.opensha.commons.param.impl
Class WarningIntegerParameter

java.lang.Object
  extended by org.opensha.commons.param.AbstractParameter<java.lang.Integer>
      extended by org.opensha.commons.param.impl.IntegerParameter
          extended by org.opensha.commons.param.impl.WarningIntegerParameter
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Parameter<?>>, Named, XMLSaveable, Parameter<java.lang.Integer>, WarningParameter<java.lang.Integer>

public class WarningIntegerParameter
extends IntegerParameter
implements WarningParameter<java.lang.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 java.lang.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  java.util.ArrayList<ParameterChangeWarningListener> 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(java.lang.String name)
          No warning constraints or absolute constraints specified.
WarningIntegerParameter(java.lang.String name, java.lang.Integer value)
          No constraints specified, all values allowed.
WarningIntegerParameter(java.lang.String name, IntegerConstraint constraint)
          Sets the name and Constraints object.
WarningIntegerParameter(java.lang.String name, IntegerConstraint constraint, java.lang.Integer value)
          Sets the name, value and constraint.
WarningIntegerParameter(java.lang.String name, IntegerConstraint constraint, java.lang.String units)
          Sets the name, constraints, and sets the units.
WarningIntegerParameter(java.lang.String name, IntegerConstraint constraint, java.lang.String units, java.lang.Integer value)
          This is the main constructor.
WarningIntegerParameter(java.lang.String name, java.lang.Integer min, java.lang.Integer max)
          Sets the name, defines the constraints min and max values.
WarningIntegerParameter(java.lang.String name, java.lang.Integer min, java.lang.Integer max, java.lang.String units)
          Sets the name, defines the constraints min and max values, and sets the units.
WarningIntegerParameter(java.lang.String name, java.lang.Integer min, java.lang.Integer max, java.lang.String units, java.lang.Integer value)
          Sets all values, and the constraint is created from the min and max values.
WarningIntegerParameter(java.lang.String name, int min, int max)
          Sets the name, defines the constraints min and max values.
WarningIntegerParameter(java.lang.String name, int min, int max, java.lang.Integer value)
          Sets the name, and value.
WarningIntegerParameter(java.lang.String name, int min, int max, java.lang.String units)
          Sets the name, defines the constraints min and max values, and sets the units.
WarningIntegerParameter(java.lang.String name, int min, int max, java.lang.String units, java.lang.Integer value)
          Sets all values, and the constraint is created from the min and max values.
WarningIntegerParameter(java.lang.String name, java.lang.String units)
          No warning constraints or absolute constraints specified.
WarningIntegerParameter(java.lang.String name, java.lang.String units, java.lang.Integer value)
          Sets the name, units and value.
 
Method Summary
 void addParameterChangeWarningListener(ParameterChangeWarningListener listener)
          Adds a ParameterChangeFailListener to the list of listeners.
 java.lang.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.
 java.lang.Integer getWarningMax()
          Proxy passthrough method to the IntegerConstraint to get the minimumn value below which warnings will be issued.
 java.lang.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(java.lang.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(java.lang.Integer value)
          Attempts to update the value of this parameter with a new Integer.
 void setValueIgnoreWarning(java.lang.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, 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, getIndependentParameterList, 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 java.lang.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 java.util.ArrayList<ParameterChangeWarningListener> 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(java.lang.String name)
No warning constraints or absolute constraints specified. All values allowed. Also sets the name of this parameter.


WarningIntegerParameter

public WarningIntegerParameter(java.lang.String name,
                               java.lang.String units)
No warning constraints or absolute constraints specified. All values allowed. Also sets the name and units of this parameter.


WarningIntegerParameter

public WarningIntegerParameter(java.lang.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(java.lang.String name,
                               int min,
                               int max,
                               java.lang.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(java.lang.String name,
                               java.lang.Integer min,
                               java.lang.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(java.lang.String name,
                               java.lang.Integer min,
                               java.lang.Integer max,
                               java.lang.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(java.lang.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(java.lang.String name,
                               IntegerConstraint constraint,
                               java.lang.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(java.lang.String name,
                               java.lang.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(java.lang.String name,
                               java.lang.String units,
                               java.lang.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(java.lang.String name,
                               int min,
                               int max,
                               java.lang.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(java.lang.String name,
                               IntegerConstraint constraint,
                               java.lang.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(java.lang.String name,
                               int min,
                               int max,
                               java.lang.String units,
                               java.lang.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(java.lang.String name,
                               java.lang.Integer min,
                               java.lang.Integer max,
                               java.lang.String units,
                               java.lang.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(java.lang.String name,
                               IntegerConstraint constraint,
                               java.lang.String units,
                               java.lang.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<java.lang.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<java.lang.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<java.lang.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<java.lang.Integer>
Throws:
ParameterException

getWarningMin

public java.lang.Integer getWarningMin()
                                throws java.lang.Exception
Proxy passthrough method to the IntegerConstraint to get the minimumn value below which warnings will be issued.

Specified by:
getWarningMin in interface WarningParameter<java.lang.Integer>
Returns:
The min value
Throws:
java.lang.Exception - Description of the Exception

getWarningMax

public java.lang.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<java.lang.Integer>
Returns:
The min value
Throws:
java.lang.Exception - Description of the Exception

setValue

public void setValue(java.lang.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<java.lang.Integer>
Overrides:
setValue in class AbstractParameter<java.lang.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(java.lang.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<java.lang.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(java.lang.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<java.lang.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<java.lang.Integer>
Parameters:
event - The event encapsulating the attempted values passed to each listener.

clone

public java.lang.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<java.lang.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<java.lang.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<java.lang.Integer>