com.jgoodies.binding.extras

Class DelayedWriteValueModel

Implemented Interfaces:
Observable, Serializable, ValueModel

public final class DelayedWriteValueModel
extends AbstractValueModel

A ValueModel that deferres write-access for a specified delay. Useful to coalesce frequent changes. For example if a heavy computation shall be performed only for a "stable" selection after a series of quick selection changes.

Wraps a given subject ValueModel and returns the subject value or the value to be set as this model's value. Observes subject value changes and forwards them to listeners of this model. If a value is set to this model, a Swing Timer is used to delay the value commit to the subject. A previously started timer - if any - will be stopped before.

TODO: Describe how and when listeners get notified about the delayed change.

TODO: Write about the recommended delay time - above the double-click time and somewhere below a second, e.g. 100ms to 200ms.

TODO: Write about a slightly different commit handling. The current implementation defers the commit until the value is stable for the specified delay; it's a DelayUntilStableForXXXmsValueModel. Another feature is to delay for a specified time but ensure that some commits and change notifications happen. The latter is a CoalescingWriteValueModel.

TODO: Summarize the differences between the DelayedReadValueModel, the DelayedWriteValueModel, and this DelayedPropertyChangeHandler.

Version:
$Revision: 1.11 $
Author:
Karsten Lentzsch
See Also:
DelayedReadValueModel, DelayedPropertyChangeHandler, javax.swing.Timer

Field Summary

Fields inherited from class com.jgoodies.binding.value.AbstractValueModel

PROPERTYNAME_VALUE

Constructor Summary

DelayedWriteValueModel(ValueModel subject, int delay)
Constructs a DelayedWriteValueModel for the given subject ValueModel and the specified Timer delay in milliseconds with coalescing disabled.
DelayedWriteValueModel(ValueModel subject, int delay, boolean coalesce)
Constructs a DelayedWriteValueModel for the given subject ValueModel and the specified Timer delay in milliseconds with coalescing disabled.

Method Summary

int
getDelay()
Returns the delay, in milliseconds, that is used to defer value commits.
Object
getValue()
Returns the subject's value or in case of a pending commit, the pending new value.
boolean
isCoalesce()
Returns if this model coalesces all pending changes or not.
void
setCoalesce(boolean b)
Sets if this model shall coalesce all pending changes or not.
void
setDelay(int delay)
Sets the delay, in milliseconds, that is used to defer value commits.
void
setValue(Object newValue)
Sets the given new value after this model's delay.
void
stop()
Stops a running timer - if any.

Methods inherited from class com.jgoodies.binding.value.AbstractValueModel

String toString, addValueChangeListener, booleanValue, doubleValue, fireValueChange, fireValueChange, fireValueChange, fireValueChange, fireValueChange, fireValueChange, fireValueChange, floatValue, getString, intValue, longValue, removeValueChangeListener, setValue, setValue, setValue, setValue, setValue

Methods inherited from class com.jgoodies.binding.beans.Model

addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, addVetoableChangeListener, equals, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, fireMultiplePropertiesChanged, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, fireVetoableChange, getPropertyChangeListeners, getPropertyChangeListeners, getVetoableChangeListeners, getVetoableChangeListeners, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, removeVetoableChangeListener

Constructor Details

DelayedWriteValueModel

public DelayedWriteValueModel(ValueModel subject,
                              int delay)
Constructs a DelayedWriteValueModel for the given subject ValueModel and the specified Timer delay in milliseconds with coalescing disabled.
Parameters:
subject - the underlying (or wrapped) ValueModel
delay - the milliseconds to wait before a change shall be committed

DelayedWriteValueModel

public DelayedWriteValueModel(ValueModel subject,
                              int delay,
                              boolean coalesce)
Constructs a DelayedWriteValueModel for the given subject ValueModel and the specified Timer delay in milliseconds with coalescing disabled.
Parameters:
subject - the underlying (or wrapped) ValueModel
delay - the milliseconds to wait before a change shall be committed
coalesce - true to coalesce all pending changes, false to fire changes with the delay when an update has been received

Method Details

getDelay

public int getDelay()
Returns the delay, in milliseconds, that is used to defer value commits.
Returns:
the delay, in milliseconds, that is used to defer value commits

getValue

public Object getValue()
Returns the subject's value or in case of a pending commit, the pending new value.
Specified by:
getValue in interface ValueModel
Returns:
the subject's current or future value.

isCoalesce

public boolean isCoalesce()
Returns if this model coalesces all pending changes or not.
Returns:
true if all pending changes will be coalesced, false if pending changes are fired with a delay when an update has been received.

setCoalesce

public void setCoalesce(boolean b)
Sets if this model shall coalesce all pending changes or not. In this case, a change event will be fired first, if no updates have been received for this model's delay. If coalesce is false, a change event will be fired with this model's delay when an update has been received.

The default value is false.

Note that this value is not the #coalesce value of this model's internal Swing timer.

Parameters:
b - true to coalesce, false to fire separate changes

setDelay

public void setDelay(int delay)
Sets the delay, in milliseconds, that is used to defer value commits.
Parameters:
delay - the delay, in milliseconds, that is used to defer value commits

setValue

public void setValue(Object newValue)
Sets the given new value after this model's delay. Does nothing if the new value and the latest pending value are the same. TODO: Describe how and when listeners get notified about the delayed value change.
Specified by:
setValue in interface ValueModel
Parameters:
newValue - the value to set

stop

public void stop()
Stops a running timer - if any. The last pending change won't be performed by the ValueUpdateListener.
Since:
1.2

Copyright © 2002-2007 JGoodies Karsten Lentzsch. All Rights Reserved.