A ValueModel that deferres updates and read-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 observes subject value changes
and forwards them to listeners of this model after a delay. If the subject
value changes, a Swing Timer is used to delay the change notification.
A previously started timer - if any - will be stopped before.
Reading this model's value returns:
a) the subject value if there's no pending update, or
b) this model's old value that will be updated after the delay.
If a value is set to this model, it immediately updates the subject value.
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 the DelayedPropertyChangeHandler.
getDelay
public int getDelay()
Returns the delay, in milliseconds, that is used to defer value change
notifications.
- the delay, in milliseconds, that is used to defer
value change notifications
getValue
public Object getValue()
Returns the subject's value or in case of a pending commit,
the pending new value.
- getValue in interface ValueModel
- the subject's current or future value.
isCoalesce
public boolean isCoalesce()
Returns if this model coalesces all pending changes or not.
true
if all pending changes will be coalesced,
false
if pending changes are fired with a delay
when an update has been received.
isPending
public boolean isPending()
Checks and answers whether this model has one or more pending changes.
true
if there are pending changes, false
if not.
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.
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 change
notifications.
delay
- the delay, in milliseconds, that is used to defer
value change notifications
setValue
public void setValue(Object newValue)
Sets the given new value immediately as the subject's new value.
Note that change notifications from the subject are deferred
by this model. Therefore listeners registered with this model
will be notified after this model's delay.
- setValue in interface ValueModel
newValue
- the value to set
stop
public void stop()
Stops a running timer. Pending changes - if any - are canceled
and won't be performed by the ValueUpdateListener
.