Revision: 1744
http://svn.sourceforge.net/spring-rich-c/?rev=1744&view=rev
Author: jhoskens
Date: 2007-04-16 04:03:30 -0700 (Mon, 16 Apr 2007)
Log Message:
-----------
Added some javadoc.
Modified Paths:
--------------
trunk/spring-richclient/support/src/main/java/org/springframework/binding/form/support/FormModelMediatingValueModel.java
Modified:
trunk/spring-richclient/support/src/main/java/org/springframework/binding/form/support/FormModelMediatingValueModel.java
===================================================================
---
trunk/spring-richclient/support/src/main/java/org/springframework/binding/form/support/FormModelMediatingValueModel.java
2007-04-10 09:17:10 UTC (rev 1743)
+++
trunk/spring-richclient/support/src/main/java/org/springframework/binding/form/support/FormModelMediatingValueModel.java
2007-04-16 11:03:30 UTC (rev 1744)
@@ -28,144 +28,240 @@
import org.springframework.richclient.util.EventListenerListHelper;
/**
- * A value model wrapper that mediates between the (wrapped) data value model
and the
- * derived view value model. Allows for value change event delivery to be
disabled.
+ * <p>
+ * A value model wrapper that mediates between the (wrapped) data value model
+ * and the derived view value model. Allows for value change event delivery to
+ * be disabled.
+ * </p>
*
+ * <p>
+ * Use the provided method [EMAIL PROTECTED]
#setDeliverValueChangeEvents(boolean)} to
+ * enable/disable the event mechanism. This makes it possible to change all
+ * valueModels and only then fire all events (as it is used in
+ * [EMAIL PROTECTED] AbstractFormModel}). Events are handled internally by the
+ * [EMAIL PROTECTED] #dirtyChangeListeners} and the [EMAIL PROTECTED]
#mediatedValueHolder}.
+ * </p>
+ *
+ * <p>
+ * As this is also a [EMAIL PROTECTED] DirtyTrackingValueModel}, the
implementation allows
+ * reverting to the original value by using [EMAIL PROTECTED]
#revertToOriginal()}, which
+ * uses the value stored in [EMAIL PROTECTED] #originalValue} to reset the
+ * wrappedValueModel. This originalValue is updated to hold the wrappedValue
+ * when using [EMAIL PROTECTED] #clearDirty()}.
+ * </p>
+ *
+ * <p>Small sketch to illustrate the positioning and usage:</p>
+ * <pre>
+ * <setup>
+ * External actor -> FormModelMediatingValueModel -> wrappedValueModel
+ * holds originalValue = ori wrappedValue = ori
+ * events = enabled
+ *
+ * <use case>
+ * events disabled -> events = disabled -> wrappedValue = ori
+ * write value A -> delagates to wrappedModel -> wrappedValue = A
+ * originalValue = ori
+ * update dirty state
+ * events enabled -> events = enabled -> wrappedValue = A
+ * sends events (dirty...)
+ * clearDirty -> originalValue = A -> wrappedValue = A
+ * OR
+ * revertToOriginal-> set originalValue on wrapped -> wrappedValue = ori
+ * update dirty state
+ * </pre>
+ *
* @author Oliver Hutchison
*/
public class FormModelMediatingValueModel extends AbstractValueModelWrapper
implements DirtyTrackingValueModel,
- PropertyChangeListener {
+ PropertyChangeListener {
- private final EventListenerListHelper dirtyChangeListeners = new
EventListenerListHelper(
- PropertyChangeListener.class);
+ /** Holds all propertyChangeListeners that are interested in Dirty
changes. */
+ private final EventListenerListHelper dirtyChangeListeners = new
EventListenerListHelper(
+ PropertyChangeListener.class);
- private boolean deliverValueChangeEvents = true;
+ /** Allows to turn off the tracking mechanism. */
+ private boolean deliverValueChangeEvents = true;
- private final ValueHolder mediatedValueHolder;
+ /** Holds the originalValue. Used to register listeners. */
+ private final ValueHolder mediatedValueHolder;
- private Object originalValue;
+ /** The original value of the wrapped ValueModel. */
+ private Object originalValue;
- private boolean oldDirty;
+ /** Previous dirty state. */
+ private boolean oldDirty;
- private final boolean trackDirty;
+ /** Dirty tracking can be disabled. */
+ private final boolean trackDirty;
- private ValueChangeDetector valueChangeDetector;
+ /** The pluggable valueChangeDetector used to track dirty changes. */
+ private ValueChangeDetector valueChangeDetector;
- public FormModelMediatingValueModel(ValueModel propertyValueModel) {
- this(propertyValueModel, true);
- }
+ /**
+ * Constructor which defaults <code>trackDirty=true</code>.
+ *
+ * @param propertyValueModel the ValueModel to mediate.
+ */
+ public FormModelMediatingValueModel(ValueModel propertyValueModel) {
+ this(propertyValueModel, true);
+ }
- public FormModelMediatingValueModel(ValueModel propertyValueModel, boolean
trackDirty) {
- super(propertyValueModel);
- super.addValueChangeListener(this);
- this.originalValue = getValue();
- this.mediatedValueHolder = new ValueHolder(originalValue);
- this.trackDirty = trackDirty;
- }
+ /**
+ * Constructor.
+ *
+ * @param propertyValueModel the valueModel to mediate.
+ * @param trackDirty disable/enable dirty tracking.
+ */
+ public FormModelMediatingValueModel(ValueModel propertyValueModel,
boolean trackDirty) {
+ super(propertyValueModel);
+ super.addValueChangeListener(this);
+ this.originalValue = getValue();
+ this.mediatedValueHolder = new ValueHolder(originalValue);
+ this.trackDirty = trackDirty;
+ }
- public void setValueSilently(Object value, PropertyChangeListener
listenerToSkip) {
- super.setValueSilently(value, this);
- if (deliverValueChangeEvents) {
- mediatedValueHolder.setValueSilently(value, listenerToSkip);
- updateDirtyState();
- }
- }
+ public void setValueSilently(Object value, PropertyChangeListener
listenerToSkip) {
+ super.setValueSilently(value, this);
+ if (deliverValueChangeEvents) {
+ mediatedValueHolder.setValueSilently(value,
listenerToSkip);
+ updateDirtyState();
+ }
+ }
- // called by the wrapped value model
- public void propertyChange(PropertyChangeEvent evt) {
- originalValue = getValue();
- if (deliverValueChangeEvents) {
- mediatedValueHolder.setValue(originalValue);
- updateDirtyState();
- }
- }
+ // called by the wrapped value model
+ public void propertyChange(PropertyChangeEvent evt) {
+ originalValue = getValue();
+ if (deliverValueChangeEvents) {
+ mediatedValueHolder.setValue(originalValue);
+ updateDirtyState();
+ }
+ }
- public void setDeliverValueChangeEvents(boolean deliverValueChangeEvents) {
- boolean oldDeliverValueChangeEvents = this.deliverValueChangeEvents;
- this.deliverValueChangeEvents = deliverValueChangeEvents;
- if (!oldDeliverValueChangeEvents && deliverValueChangeEvents) {
- mediatedValueHolder.setValue(getValue());
- updateDirtyState();
- }
- }
+ /**
+ * <p>
+ * Enable/disable the event mechanism. Makes it possible to control the
+ * timing of event firing (delay the events).
+ * </p>
+ *
+ * <p>
+ * When disabling, no dirty events will be fired and the mediating
+ * valueHolder will not set it's value. The latter results in not firing
+ * other events like valueChangedEvents.
+ * </p>
+ * <p>
+ * When enabling, original (stored) value is compared to the newer
value in
+ * the wrapped model and the necessary events are fired
+ * (dirty/valueChanged).
+ * <p>
+ *
+ * @param deliverValueChangeEvents boolean to enable/disable event
+ * mechanism.
+ */
+ public void setDeliverValueChangeEvents(boolean
deliverValueChangeEvents) {
+ boolean oldDeliverValueChangeEvents =
this.deliverValueChangeEvents;
+ this.deliverValueChangeEvents = deliverValueChangeEvents;
+ if (!oldDeliverValueChangeEvents && deliverValueChangeEvents) {
+ mediatedValueHolder.setValue(getValue());
+ updateDirtyState();
+ }
+ }
- public boolean isDirty() {
- return trackDirty &&
getValueChangeDetector().hasValueChanged(originalValue, getValue());
- }
+ public boolean isDirty() {
+ return trackDirty &&
getValueChangeDetector().hasValueChanged(originalValue, getValue());
+ }
- public void clearDirty() {
- if (isDirty()) {
- originalValue = getValue();
- updateDirtyState();
- }
- }
+ public void clearDirty() {
+ if (isDirty()) {
+ originalValue = getValue();
+ updateDirtyState();
+ }
+ }
- public void revertToOriginal() {
- if (isDirty()) {
- setValue(originalValue);
- }
- }
+ public void revertToOriginal() {
+ if (isDirty()) {
+ setValue(originalValue);
+ }
+ }
- protected void updateDirtyState() {
- boolean dirty = isDirty();
- if (oldDirty != dirty) {
- oldDirty = dirty;
- firePropertyChange(DIRTY_PROPERTY, !dirty, dirty);
- }
- }
+ /**
+ * Check the dirty state and fire events if needed.
+ */
+ protected void updateDirtyState() {
+ boolean dirty = isDirty();
+ if (oldDirty != dirty) {
+ oldDirty = dirty;
+ firePropertyChange(DIRTY_PROPERTY, !dirty, dirty);
+ }
+ }
- public void setValueChangeDetector(ValueChangeDetector
valueChangeDetector) {
- this.valueChangeDetector = valueChangeDetector;
- }
+ /**
+ * @param valueChangeDetector set the [EMAIL PROTECTED]
ValueChangeDetector} to use
+ * when checking the dirty state.
+ */
+ public void setValueChangeDetector(ValueChangeDetector
valueChangeDetector) {
+ this.valueChangeDetector = valueChangeDetector;
+ }
- protected ValueChangeDetector getValueChangeDetector() {
- if (valueChangeDetector == null) {
- valueChangeDetector =
(ValueChangeDetector)ApplicationServicesLocator.services().getService(ValueChangeDetector.class);
- }
- return valueChangeDetector;
- }
+ /**
+ * @return a [EMAIL PROTECTED] ValueChangeDetector} to use when
checking the dirty
+ * state.
+ */
+ protected ValueChangeDetector getValueChangeDetector() {
+ if (valueChangeDetector == null) {
+ valueChangeDetector = (ValueChangeDetector)
ApplicationServicesLocator.services().getService(
+ ValueChangeDetector.class);
+ }
+ return valueChangeDetector;
+ }
- public void addValueChangeListener(PropertyChangeListener listener) {
- mediatedValueHolder.addValueChangeListener(listener);
- }
+ public void addValueChangeListener(PropertyChangeListener listener) {
+ mediatedValueHolder.addValueChangeListener(listener);
+ }
- public void removeValueChangeListener(PropertyChangeListener listener) {
- mediatedValueHolder.removeValueChangeListener(listener);
- }
+ public void removeValueChangeListener(PropertyChangeListener listener) {
+ mediatedValueHolder.removeValueChangeListener(listener);
+ }
- public void addPropertyChangeListener(PropertyChangeListener listener) {
- throw new UnsupportedOperationException("not implemented");
- }
+ public void addPropertyChangeListener(PropertyChangeListener listener) {
+ throw new UnsupportedOperationException("not implemented");
+ }
- public void addPropertyChangeListener(String propertyName,
PropertyChangeListener listener) {
- if (DIRTY_PROPERTY.equals(propertyName)) {
- dirtyChangeListeners.add(listener);
- }
- else if (VALUE_PROPERTY.equals(propertyName)) {
- addValueChangeListener(listener);
- }
- }
+ public void addPropertyChangeListener(String propertyName,
PropertyChangeListener listener) {
+ if (DIRTY_PROPERTY.equals(propertyName)) {
+ dirtyChangeListeners.add(listener);
+ }
+ else if (VALUE_PROPERTY.equals(propertyName)) {
+ addValueChangeListener(listener);
+ }
+ }
- public void removePropertyChangeListener(PropertyChangeListener listener) {
- throw new UnsupportedOperationException("not implemented");
- }
+ public void removePropertyChangeListener(PropertyChangeListener
listener) {
+ throw new UnsupportedOperationException("not implemented");
+ }
- public void removePropertyChangeListener(String propertyName,
PropertyChangeListener listener) {
- if (DIRTY_PROPERTY.equals(propertyName)) {
- dirtyChangeListeners.remove(listener);
- }
- else if (VALUE_PROPERTY.equals(propertyName)) {
- removeValueChangeListener(listener);
- }
- }
+ public void removePropertyChangeListener(String propertyName,
PropertyChangeListener listener) {
+ if (DIRTY_PROPERTY.equals(propertyName)) {
+ dirtyChangeListeners.remove(listener);
+ }
+ else if (VALUE_PROPERTY.equals(propertyName)) {
+ removeValueChangeListener(listener);
+ }
+ }
- protected final void firePropertyChange(String propertyName, boolean
oldValue, boolean newValue) {
- if (DIRTY_PROPERTY.equals(propertyName)) {
- PropertyChangeEvent evt = new PropertyChangeEvent(this,
propertyName, Boolean.valueOf(oldValue),
- Boolean.valueOf(newValue));
- for (Iterator i = dirtyChangeListeners.iterator(); i.hasNext();) {
- ((PropertyChangeListener)i.next()).propertyChange(evt);
- }
- }
- }
+ /**
+ * Handles the dirty event firing.
+ *
+ * @param propertyName implementation only handles DIRTY_PROPERTY.
+ * @param oldValue
+ * @param newValue
+ */
+ protected final void firePropertyChange(String propertyName, boolean
oldValue, boolean newValue) {
+ if (DIRTY_PROPERTY.equals(propertyName)) {
+ PropertyChangeEvent evt = new PropertyChangeEvent(this,
propertyName, Boolean.valueOf(oldValue), Boolean
+ .valueOf(newValue));
+ for (Iterator i = dirtyChangeListeners.iterator();
i.hasNext();) {
+ ((PropertyChangeListener)
i.next()).propertyChange(evt);
+ }
+ }
+ }
}
\ No newline at end of file
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
spring-rich-c-cvs mailing list
spring-rich-c-cvs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/spring-rich-c-cvs
