com.jgoodies.binding.beans

Class DelayedPropertyChangeHandler

Implemented Interfaces:
PropertyChangeListener

public abstract class DelayedPropertyChangeHandler
extends java.lang.Object
implements 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.

Version:
$Revision: 1.15 $
Author:
Karsten Lentzsch
Since:
1.1
See Also:
DelayedReadValueModel, DelayedWriteValueModel, javax.swing.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(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(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.

Field Details

DEFAULT_DELAY

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

Constructor Details

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

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

Method Details

delayedPropertyChange

public abstract void delayedPropertyChange(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

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

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.

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(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.
Parameters:
evt - the PropertyChangeEvent describing the event source and the property that has changed

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

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
Since:
1.5

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

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