com.jgoodies.binding.value
Class DelayedReadValueModel

java.lang.Object
  com.jgoodies.binding.beans.Model
      com.jgoodies.binding.value.AbstractValueModel
          com.jgoodies.binding.value.DelayedReadValueModel

All Implemented Interfaces:

Observable, ValueModel, java.io.Serializable

public final class DelayedReadValueModel
extends AbstractValueModel

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.

Since:

1.1

Version:

$Revision: 1.11 $

Author:

Karsten Lentzsch

See Also:

Timer, Serialized Form

Field Summary

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

PROPERTYNAME_VALUE

Constructor Summary

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

DelayedReadValueModel(ValueModel subject, int delay, boolean coalesce)
Constructs a DelayedReadValueModel for the given subject ValueModel and the specified Timer delay in milliseconds using the given coalesce mode.

Method Summary

int	getDelay() Returns the delay, in milliseconds, that is used to defer value change notifications.
java.lang.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.
boolean	isPending() Checks and answers whether this model has one or more pending changes.
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 change notifications.
void	setValue(java.lang.Object newValue) Sets the given new value immediately as the subject's new value.
void	stop() Stops a running timer.

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

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

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

DelayedReadValueModel

public DelayedReadValueModel(ValueModel subject,
                             int delay)

Constructs a DelayedReadValueModel 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

Throws:

java.lang.IllegalArgumentException - if the delay is negative

DelayedReadValueModel

public DelayedReadValueModel(ValueModel subject,
                             int delay,
                             boolean coalesce)

Constructs a DelayedReadValueModel for the given subject ValueModel and the specified Timer delay in milliseconds using the given coalesce mode.

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

Throws:

java.lang.IllegalArgumentException - if the delay is negative

See Also:

setCoalesce(boolean)

Method Detail

getValue

public java.lang.Object getValue()

Returns the subject's value or in case of a pending commit, the pending new value.

Returns:

the subject's current or future value.

setValue

public void setValue(java.lang.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.

Parameters:

newValue - the value to set

getDelay

public int getDelay()

Returns the delay, in milliseconds, that is used to defer value change notifications.

Returns:

the delay, in milliseconds, that is used to defer value change notifications

See Also:

setDelay(int)

setDelay

public void setDelay(int delay)

Sets the delay, in milliseconds, that is used to defer value change notifications.

Parameters:

delay - the delay, in milliseconds, that is used to defer value change notifications

See Also:

getDelay()

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.

See Also:

setCoalesce(boolean)

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

stop

public void stop()

Stops a running timer. Pending changes - if any - are canceled and won't be performed by the ValueUpdateListener.

Since:

1.2

isPending

public boolean isPending()

Checks and answers whether this model has one or more pending changes.

Returns:

true if there are pending changes, false if not.

Since:

2.0.4