com.jgoodies.binding.beans
Class DelayedPropertyChangeHandler

java.lang.Object
  extended by com.jgoodies.binding.beans.DelayedPropertyChangeHandler
All Implemented Interfaces:
java.beans.PropertyChangeListener, java.util.EventListener

public abstract class DelayedPropertyChangeHandler
extends java.lang.Object
implements java.beans.PropertyChangeListener

A PropertyChangeListener that is intended to handle property changes after a specified delay. Useful to defer changes until a stable state is reached. For example if you look up a persistent object for a selection in a list. You don't want to find and transport objects that the user selects temporarily; you want to get only a stable selection. Or if you want to validate on every key typed, you may delay the validation until no key has been typed for a given time.

If this handler is notified about a property change it stores the PropertyChangeEvent it has received in #propertyChange, and starts a Swing Timer that will call #delayedPropertyChange after a delay. In coalescing mode a previously started timer - if any - will be stopped before. In other words, the timer is restarted.

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

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

Since:
1.1
Version:
$Revision: 1.17 $
Author:
Karsten Lentzsch
See Also:
DelayedReadValueModel, DelayedWriteValueModel, Timer

Field Summary
static int DEFAULT_DELAY
          The delay in milliseconds used as default in the no-arg constructor.
 
Constructor Summary
DelayedPropertyChangeHandler()
          Constructs a DelayedPropertyChangeHandler with a default delay.
DelayedPropertyChangeHandler(int delay)
          Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the coalesce disabled.
DelayedPropertyChangeHandler(int delay, boolean coalesce)
          Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the given coalesce mode.
 
Method Summary
abstract  void delayedPropertyChange(java.beans.PropertyChangeEvent evt)
          This method gets called after this handler's delay if a bound property has changed.
 int getDelay()
          Returns the delay, in milliseconds, that is used to defer value change notifications.
 boolean isCoalesce()
          Returns if this model coalesces all pending changes or not.
 boolean isPending()
          Checks and answers whether there are pending events.
 void propertyChange(java.beans.PropertyChangeEvent evt)
          This handler has been notified about a change in a bound property.
 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 stop()
          Stops a running timer.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_DELAY

public static final int DEFAULT_DELAY
The delay in milliseconds used as default in the no-arg constructor.

See Also:
Constant Field Values
Constructor Detail

DelayedPropertyChangeHandler

public DelayedPropertyChangeHandler()
Constructs a DelayedPropertyChangeHandler with a default delay.


DelayedPropertyChangeHandler

public DelayedPropertyChangeHandler(int delay)
Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the coalesce disabled.

Parameters:
delay - the milliseconds to wait before the delayed property change will be performed
Throws:
java.lang.IllegalArgumentException - if the delay is negative

DelayedPropertyChangeHandler

public DelayedPropertyChangeHandler(int delay,
                                    boolean coalesce)
Constructs a DelayedPropertyChangeHandler with the specified Timer delay and the given coalesce mode.

Parameters:
delay - the milliseconds to wait before the delayed property change will be performed
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

getDelay

public final 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
Since:
1.5
See Also:
setDelay(int)

setDelay

public final 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
Throws:
java.lang.IllegalArgumentException - if the delay is negative
Since:
1.5
See Also:
getDelay()

isCoalesce

public final 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 final 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 final void stop()
Stops a running timer. Pending events - if any - are canceled and won't be delivered to #delayedPropertyChange.

Since:
1.2

isPending

public final boolean isPending()
Checks and answers whether there are pending events.

Returns:
true if there are pending events, false if not.
Since:
2.0.4

propertyChange

public final void propertyChange(java.beans.PropertyChangeEvent evt)
This handler has been notified about a change in a bound property. Stores the given event, then starts a timer that'll call #delayedPropertyChange after this handler's delay. If coalescing is enabled, a previously started timer - if any - if stopped before. In other words, the timer is restarted.

Specified by:
propertyChange in interface java.beans.PropertyChangeListener
Parameters:
evt - the PropertyChangeEvent describing the event source and the property that has changed

delayedPropertyChange

public abstract void delayedPropertyChange(java.beans.PropertyChangeEvent evt)
This method gets called after this handler's delay if a bound property has changed. The event is the pending event as stored in #propertyChange.

Parameters:
evt - the PropertyChangeEvent describing the event source and the property that has changed


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