com.jgoodies.binding.beans
Class DelayedPropertyChangeHandler

java.lang.Object
  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.15 $

Author:

Karsten Lentzsch

See Also:

DelayedReadValueModel, com.jgoodies.binding.extras.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