org.knime.core.node.defaultnodesettings
Class SettingsModel

java.lang.Object
  extended by org.knime.core.node.defaultnodesettings.SettingsModel
Direct Known Subclasses:
DialogComponent.EmptySettingsModel, SettingsModelBoolean, SettingsModelColorNameColumns, SettingsModelDoubleRange, SettingsModelFilterString, SettingsModelNumber, SettingsModelPCADimensions, SettingsModelString, SettingsModelStringArray

public abstract class SettingsModel
extends Object

Abstract implementation of an encapsulating class holding a (usually rather basic) model of NodeModel Settings. The main motivation for this class is the need to access (read/write) the settings of model at various places (NodeModel, NodeDialog) and the need to unify and simplify this. It also enables the user to register to change-events so that other models/components can be updated accordingly (enable/disable...).

Author:
M. Berthold, University of Konstanz

Constructor Summary
SettingsModel()
          Default constructor.
 
Method Summary
 void addChangeListener(ChangeListener l)
          Adds a listener (to the end of the listener list) which is notified, whenever a new values is set in the model or the enable status changes.
protected abstract
<T extends SettingsModel>
T
createClone()
           
<T extends SettingsModel>
T
createCloneWithValidatedValue(NodeSettingsRO settings)
          Creates a new settings model with identical values for everything except the stored value (also except the list of listeners).
(package private)  void dlgLoadSettingsFrom(NodeSettingsRO settings, PortObjectSpec[] specs)
          This is the method called from the default dialog component to load the model specific settings from the settings object.
(package private)  void dlgSaveSettingsTo(NodeSettingsWO settings)
          This method is called by the default dialog to save the model specific settings into the settings object.
protected abstract  String getConfigName()
           
protected abstract  String getModelTypeID()
          Each settings model provides an ID which will be stored with its values.
 boolean isEnabled()
           
protected abstract  void loadSettingsForDialog(NodeSettingsRO settings, PortObjectSpec[] specs)
          Read the value(s) of this settings model from configuration object.
protected abstract  void loadSettingsForModel(NodeSettingsRO settings)
          Read value(s) of this settings model from the configuration object.
 void loadSettingsFrom(NodeSettingsRO settings)
          Read value(s) of this component model from configuration object.
protected  void notifyChangeListeners()
          Notifies all registered listeners about a new model content.
protected  void prependChangeListener(ChangeListener l)
          Adds a listener (to the beginning of the listener list) which is notified, whenever a new values is set in the model or the enable status changes.
 void removeChangeListener(ChangeListener l)
          Remove a specific listener.
protected abstract  void saveSettingsForDialog(NodeSettingsWO settings)
          Write value(s) of this component model to configuration object.
protected abstract  void saveSettingsForModel(NodeSettingsWO settings)
          Write value(s) of this settings model to configuration object.
NOTE: Don't call this method directly, rather call saveSettingsTo.
 void saveSettingsTo(NodeSettingsWO settings)
          Write value(s) of this setttings model to configuration object.
 void setEnabled(boolean enabled)
          Sets the enabled status of the model.
abstract  String toString()
          Derived classes should print their class name plus the config name for nice and useful error messages.
 void validateSettings(NodeSettingsRO settings)
          Read the expected values from the settings object, without assigning them to the internal variables!
protected abstract  void validateSettingsForModel(NodeSettingsRO settings)
          Read the expected values from the settings object, without assigning them to the internal variables! (Is not called when the model was disabled at the time the settings were saved.)
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

SettingsModel

public SettingsModel()
Default constructor.

Method Detail

createCloneWithValidatedValue

public final <T extends SettingsModel> T createCloneWithValidatedValue(NodeSettingsRO settings)
                                                            throws InvalidSettingsException
Creates a new settings model with identical values for everything except the stored value (also except the list of listeners). The value stored in the model will be retrieved from the specified settings object. If the settings object doesn't contain a (valid) value it will throw an InvalidSettingsException.

Type Parameters:
T - the actual type
Parameters:
settings - the object to read the new model's value(s) from
Returns:
a new settings model with the same constraints and configName but a value read from the specified settings object.
Throws:
InvalidSettingsException - if the settings object passed doesn't contain a valid value for the newly created settings model.

createClone

protected abstract <T extends SettingsModel> T createClone()
Type Parameters:
T - determined by the implementation class. Must be the same than the class implementing this method.
Returns:
a new instance of the same object with identical state and value(s).

getModelTypeID

protected abstract String getModelTypeID()
Each settings model provides an ID which will be stored with its values. This is to ensure that the same type of model is used to read the values back. Otherwise an assertion will go off. Make sure to provide a unique ID - and to re-use that ID in all compatible models. IntegerModels for example should use the same ID as BoundedInteger models.

Returns:
a string that identifies all models that are able (and empowered) to read the values stored by this model.

getConfigName

protected abstract String getConfigName()
Returns:
the name provided at settings model construction time. The id associated with the value.

loadSettingsForDialog

protected abstract void loadSettingsForDialog(NodeSettingsRO settings,
                                              PortObjectSpec[] specs)
                                       throws NotConfigurableException
Read the value(s) of this settings model from configuration object. If the value is not stored in the config, the objects value must remain unchanged. Called only from within the components using this model. If the model is disabled it should not throw the exception.
This method must always notify change listeners!!
NOTE: Do not call this method directly, rather call dlgLoadSettingsFrom

Parameters:
settings - The NodeSettings to read from.
specs - The input specs.
Throws:
NotConfigurableException - if the specs are not good enough to

dlgLoadSettingsFrom

final void dlgLoadSettingsFrom(NodeSettingsRO settings,
                               PortObjectSpec[] specs)
                        throws NotConfigurableException
This is the method called from the default dialog component to load the model specific settings from the settings object. It calls the model specific implementations.

Parameters:
settings - The NodeSettings to read from.
specs - The input specs.
Throws:
NotConfigurableException - if the specs are not good enough to load settings for this model

saveSettingsForDialog

protected abstract void saveSettingsForDialog(NodeSettingsWO settings)
                                       throws InvalidSettingsException
Write value(s) of this component model to configuration object. Called only from within the components using this model.
NOTE: Don't call this method directly, rather use dlgSaveSettingsTo.

Parameters:
settings - The NodeSettings to read from.
Throws:
InvalidSettingsException - if the user has entered wrong values.

dlgSaveSettingsTo

final void dlgSaveSettingsTo(NodeSettingsWO settings)
                      throws InvalidSettingsException
This method is called by the default dialog to save the model specific settings into the settings object. It saves the model's ID before it delegates to the derived implementation.

Parameters:
settings - The NodeSettings to read from.
Throws:
InvalidSettingsException - if the user has entered wrong values.

addChangeListener

public void addChangeListener(ChangeListener l)
Adds a listener (to the end of the listener list) which is notified, whenever a new values is set in the model or the enable status changes. Does nothing if the listener is already registered.

Parameters:
l - listener to add.

prependChangeListener

protected void prependChangeListener(ChangeListener l)
Adds a listener (to the beginning of the listener list) which is notified, whenever a new values is set in the model or the enable status changes. Does nothing if the listener is already registered.

Parameters:
l - listener to add.

removeChangeListener

public void removeChangeListener(ChangeListener l)
Remove a specific listener.

Parameters:
l - listener to remove.

notifyChangeListeners

protected void notifyChangeListeners()
Notifies all registered listeners about a new model content. Call this, whenever the value in the model changes!


setEnabled

public void setEnabled(boolean enabled)
Sets the enabled status of the model. If a model is disabled it doesn't validate new values or save it's current value into a settings object. Also loading will be skipped. (The model does store its enable status in the settings object though.)

Parameters:
enabled - the new enable status. If true the model saves/validates/loads its value, if false, all these operations are skipped.

isEnabled

public boolean isEnabled()
Returns:
the current enable status of the model.
See Also:
setEnabled(boolean)

validateSettings

public final void validateSettings(NodeSettingsRO settings)
                            throws InvalidSettingsException
Read the expected values from the settings object, without assigning them to the internal variables!

Parameters:
settings - the object to read the value(s) from
Throws:
InvalidSettingsException - if the value(s) in the settings object are invalid.

validateSettingsForModel

protected abstract void validateSettingsForModel(NodeSettingsRO settings)
                                          throws InvalidSettingsException
Read the expected values from the settings object, without assigning them to the internal variables! (Is not called when the model was disabled at the time the settings were saved.)

Parameters:
settings - the object to read the value(s) from
Throws:
InvalidSettingsException - if the value(s) in the settings object are invalid.

loadSettingsFrom

public final void loadSettingsFrom(NodeSettingsRO settings)
                            throws InvalidSettingsException
Read value(s) of this component model from configuration object. If the value is not stored in the config, an exception will be thrown.

Parameters:
settings - The NodeSettings to read from.
Throws:
InvalidSettingsException - if load fails.

loadSettingsForModel

protected abstract void loadSettingsForModel(NodeSettingsRO settings)
                                      throws InvalidSettingsException
Read value(s) of this settings model from the configuration object. If the value is not stored in the config, an exception will be thrown.
NOTE: Don't call this method directly, rather call loadSettingsFrom.

Parameters:
settings - The NodeSettings to read from.
Throws:
InvalidSettingsException - if load fails.

saveSettingsTo

public final void saveSettingsTo(NodeSettingsWO settings)
Write value(s) of this setttings model to configuration object.

Parameters:
settings - The NodeSettings to write into.

saveSettingsForModel

protected abstract void saveSettingsForModel(NodeSettingsWO settings)
Write value(s) of this settings model to configuration object.
NOTE: Don't call this method directly, rather call saveSettingsTo.

Parameters:
settings - The NodeSettings to write into.

toString

public abstract String toString()
Derived classes should print their class name plus the config name for nice and useful error messages. Like that,
return getClass().getSimpleName() + " ('" + m_configName + "')";

Overrides:
toString in class Object


Copyright, 2003 - 2010. All rights reserved.
University of Konstanz, Germany.
Chair for Bioinformatics and Information Mining, Prof. Dr. Michael R. Berthold.
You may not modify, publish, transmit, transfer or sell, reproduce, create derivative works from, distribute, perform, display, or in any way exploit any of the content, in whole or in part, except as otherwise expressly permitted in writing by the copyright owner or as specified in the license file distributed with this product.