Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.jgoodies.binding.beans
Class ExtendedPropertyChangeSupport

    java.lang.Object
      java.beans.PropertyChangeSupport
          com.jgoodies.binding.beans.ExtendedPropertyChangeSupport

All Implemented Interfaces:
  Serializable

    public final class ExtendedPropertyChangeSupport

extends PropertyChangeSupport

Differs from its superclass `PropertyChangeSupport` in that it can check for changed values using `#equals` or `==`. Useful if you want to ensure that a `PropertyChangeEvent` is fired if the old and new value are not the same but if they are equal.

The Java Bean Secification recommends to not throw a PropertyChangeEvent if the old and new value of a bound Bean property are equal (see chapter 7.4.4). This can reduce the number of events fired and helps avoid loops. Nevertheless a bound property may fire an event if the old and new value are equal.

An example for a condition where the identity check `==` is required and the `#equals` test fails is class `SelectionInList`. If the contained `ListModel` changes its value, an internal listener is removed from the old value and added to the new value. The listener must be moved from the old instance to the new instance even if these are equal. The `PropertyChangeSupport` doesn't fire a property change event if such a `ListModel` is implemented as a `List`. This is because instances of `List` are equal if and only if all list members are equal and if they are in the same sequence.

This class provides two means to fire an event if the old and new value are equal but not the same. First, you enable the identity check in constructor `ExtendedPropertyChangeSupport(Object, boolean)`. By default all calls to `#firePropertyChange` will then check the identity, not the equality. Second, you can invoke `firePropertyChange(PropertyChangeEvent, boolean)` or `firePropertyChange(String, Object, Object, boolean)` and enable or disable the identity check for this call only.

TODO: (Issue #5) Use WeakReferences to refer to registered listeners.

TODO: (Issue #6) Add an optional check for valid property name when adding a listener for a specific property.

TODO: (Issue #7) Add an optional strict check for existing property names when firing a named property change.

TODO: (Issue #8) Add an option to ensure that update notifications are performed in the event dispatch thread. In case a bean is changed in a thread other than the event dispatch thread, such a feature would help complying with Swing's single thread rule.

TODO: (Issue #11) Consider adding an option that saves update notifications if 'checkIdentity' is true but the value types can be compared safely via #equals, for example Strings, Booleans and Numbers.

Version:
  $Revision: 1.3 $
Author:
  Mattias Neuling, Karsten Lentzsch
See Also:
  `PropertyChangeSupport`, `PropertyChangeEvent`, `PropertyChangeListener`, `Object.equals(Object)`, `List.equals(Object)`, Serialized Form

Constructor Summary
`ExtendedPropertyChangeSupport(Object sourceBean)` Constructs an `ExtendedPropertyChangeSupport` object.
`ExtendedPropertyChangeSupport(Object sourceBean, boolean checkIdentityDefault)` Constructs an `ExtendedPropertyChangeSupport` object with the specified default test method for differences between the old and new property values.

Method Summary
`void` | `firePropertyChange(PropertyChangeEvent evt)` Fires the specified PropertyChangeEvent to any registered listeners.
`void` | `firePropertyChange(PropertyChangeEvent evt, boolean checkIdentity)` Fires an existing PropertyChangeEvent to any registered listeners.
`void` | `firePropertyChange(String propertyName, Object oldValue, Object newValue)` Reports a bound property update to any registered listeners.
`void` | `firePropertyChange(String propertyName, Object oldValue, Object newValue, boolean checkIdentity)` Reports a bound property update to any registered listeners.

Methods inherited from class java.beans.PropertyChangeSupport
`addPropertyChangeListener, addPropertyChangeListener, fireIndexedPropertyChange, fireIndexedPropertyChange, fireIndexedPropertyChange, firePropertyChange, firePropertyChange, getPropertyChangeListeners, getPropertyChangeListeners, hasListeners, removePropertyChangeListener, removePropertyChangeListener`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### ExtendedPropertyChangeSupport

    public ExtendedPropertyChangeSupport(Object sourceBean)

  Constructs an `ExtendedPropertyChangeSupport` object.

  Parameters:
    `sourceBean` - The bean to be given as the source for any events.

### ExtendedPropertyChangeSupport

    public ExtendedPropertyChangeSupport(Object sourceBean,
                                         boolean checkIdentityDefault)

  Constructs an `ExtendedPropertyChangeSupport` object with the specified default test method for differences between the old and new property values.

  Parameters:
    `sourceBean` - The object provided as the source for any generated events.
    `checkIdentityDefault` - true enables the identity check by default

Method Detail

### firePropertyChange

    public void firePropertyChange(PropertyChangeEvent evt)

  Fires the specified PropertyChangeEvent to any registered listeners. Uses the default test (`#equals` vs. `==`) to determine whether the event's old and new values are different. No event is fired if old and new value are the same.

  Overrides:
    `firePropertyChange` in class `PropertyChangeSupport`
  Parameters:
    `evt` - The PropertyChangeEvent object.
  See Also:
    `PropertyChangeSupport.firePropertyChange(PropertyChangeEvent)`

### firePropertyChange

    public void firePropertyChange(String propertyName,
                                   Object oldValue,
                                   Object newValue)

  Reports a bound property update to any registered listeners. Uses the default test (`#equals` vs. `==`) to determine whether the event's old and new values are different. No event is fired if old and new value are the same.

  Overrides:
    `firePropertyChange` in class `PropertyChangeSupport`
  Parameters:
    `propertyName` - The programmatic name of the property that was changed.
    `oldValue` - The old value of the property.
    `newValue` - The new value of the property.
  See Also:
    `PropertyChangeSupport.firePropertyChange(String, Object, Object)`

### firePropertyChange

    public void firePropertyChange(PropertyChangeEvent evt,
                                   boolean checkIdentity)

  Fires an existing PropertyChangeEvent to any registered listeners. The boolean parameter specifies whether differences between the old and new value are tested using `==` or `#equals`. No event is fired if old and new value are the same.

  Parameters:
    `evt` - The PropertyChangeEvent object.
    `checkIdentity` - true to check differences using `==` false to use `#equals`.

### firePropertyChange

    public void firePropertyChange(String propertyName,
                                   Object oldValue,
                                   Object newValue,
                                   boolean checkIdentity)

  Reports a bound property update to any registered listeners. No event is fired if the old and new value are the same. If checkIdentity is `true` an event is fired in all other cases. If this parameter is `false`, an event is fired if old and new values are not equal.

  Parameters:
    `propertyName` - The programmatic name of the property that was changed.
    `oldValue` - The old value of the property.
    `newValue` - The new value of the property.
    `checkIdentity` - true to check differences using `==` false to use `#equals`.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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