java.beans

Class PropertyChangeSupport

Implemented Interfaces:
Serializable
Known Direct Subclasses:
SwingPropertyChangeSupport

public class PropertyChangeSupport
extends Object
implements Serializable

PropertyChangeSupport makes it easy to fire property change events and handle listeners. It allows chaining of listeners, as well as filtering by property name. In addition, it will serialize only those listeners which are serializable, ignoring the others without problem. This class is thread-safe.
Since:
1.1
See Also:
Serialized Form

Constructor Summary

PropertyChangeSupport(Object source)
Create a PropertyChangeSupport to work with a specific source bean.

Method Summary

void
addPropertyChangeListener(PropertyChangeListener l)
Adds a PropertyChangeListener to the list of global listeners.
void
addPropertyChangeListener(String propertyName, PropertyChangeListener l)
Adds a PropertyChangeListener listening on the specified property.
void
fireIndexedPropertyChange(String name, int index, boolean oldValue, boolean newValue)
Fire an indexed property change event.
void
fireIndexedPropertyChange(String name, int index, int oldValue, int newValue)
Fire an indexed property change event.
void
fireIndexedPropertyChange(String name, int index, Object oldValue, Object newValue)
Fire an indexed property change event.
void
firePropertyChange(PropertyChangeEvent event)
Fire a PropertyChangeEvent to all the global listeners, and to all the listeners for the specified property name.
void
firePropertyChange(String propertyName, boolean oldVal, boolean newVal)
Fire a PropertyChangeEvent containing the old and new values of the property to all the global listeners, and to all the listeners for the specified property name.
void
firePropertyChange(String propertyName, int oldVal, int newVal)
Fire a PropertyChangeEvent containing the old and new values of the property to all the global listeners, and to all the listeners for the specified property name.
void
firePropertyChange(String propertyName, Object oldVal, Object newVal)
Fire a PropertyChangeEvent containing the old and new values of the property to all the global listeners, and to all the listeners for the specified property name.
PropertyChangeListener[]
getPropertyChangeListeners()
Returns an array of all registered property change listeners.
PropertyChangeListener[]
getPropertyChangeListeners(String propertyName)
Returns an array of all property change listeners registered under the given property name.
boolean
hasListeners(String propertyName)
Tell whether the specified property is being listened on or not.
void
removePropertyChangeListener(PropertyChangeListener l)
Removes a PropertyChangeListener from the list of global listeners.
void
removePropertyChangeListener(String propertyName, PropertyChangeListener l)
Removes a PropertyChangeListener from listening to a specific property.

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PropertyChangeSupport

public PropertyChangeSupport(Object source)
Create a PropertyChangeSupport to work with a specific source bean.
Parameters:
source - the source bean to use
Throws:
NullPointerException - if source is null

Method Details

addPropertyChangeListener

public void addPropertyChangeListener(PropertyChangeListener l)
Adds a PropertyChangeListener to the list of global listeners. All property change events will be sent to this listener. The listener add is not unique: that is, n adds with the same listener will result in n events being sent to that listener for every property change. Adding a null listener is silently ignored. This method will unwrap a PropertyChangeListenerProxy, registering the underlying delegate to the named property list.
Parameters:
l - the listener to add

addPropertyChangeListener

public void addPropertyChangeListener(String propertyName,
                                      PropertyChangeListener l)
Adds a PropertyChangeListener listening on the specified property. Events will be sent to the listener only if the property name matches. The listener add is not unique; that is, n adds on a particular property for a particular listener will result in n events being sent to that listener when that property is changed. The effect is cumulative, too; if you are registered to listen to receive events on all property changes, and then you register on a particular property, you will receive change events for that property twice. Adding a null listener is silently ignored. This method will unwrap a PropertyChangeListenerProxy, registering the underlying delegate to the named property list if the names match, and discarding it otherwise.
Parameters:
propertyName - the name of the property to listen on
l - the listener to add
Throws:
NullPointerException - if propertyName is null

fireIndexedPropertyChange

public void fireIndexedPropertyChange(String name,
                                      int index,
                                      boolean oldValue,
                                      boolean newValue)
Fire an indexed property change event. This will only fire an event if the old and new values are not equal.
Parameters:
name - the name of the property which changed
index - the index of the property which changed
oldValue - the old value of the property
newValue - the new value of the property
Since:
1.5

fireIndexedPropertyChange

public void fireIndexedPropertyChange(String name,
                                      int index,
                                      int oldValue,
                                      int newValue)
Fire an indexed property change event. This will only fire an event if the old and new values are not equal.
Parameters:
name - the name of the property which changed
index - the index of the property which changed
oldValue - the old value of the property
newValue - the new value of the property
Since:
1.5

fireIndexedPropertyChange

public void fireIndexedPropertyChange(String name,
                                      int index,
                                      Object oldValue,
                                      Object newValue)
Fire an indexed property change event. This will only fire an event if the old and new values are not equal and not null.
Parameters:
name - the name of the property which changed
index - the index of the property which changed
oldValue - the old value of the property
newValue - the new value of the property
Since:
1.5

firePropertyChange

public void firePropertyChange(PropertyChangeEvent event)
Fire a PropertyChangeEvent to all the global listeners, and to all the listeners for the specified property name. This does nothing if old and new values of the event are equal.
Parameters:
event - the event to fire
Throws:
NullPointerException - if event is null

firePropertyChange

public void firePropertyChange(String propertyName,
                               boolean oldVal,
                               boolean newVal)
Fire a PropertyChangeEvent containing the old and new values of the property to all the global listeners, and to all the listeners for the specified property name. This does nothing if old and new are equal.
Parameters:
propertyName - the name of the property that changed
oldVal - the old value
newVal - the new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               int oldVal,
                               int newVal)
Fire a PropertyChangeEvent containing the old and new values of the property to all the global listeners, and to all the listeners for the specified property name. This does nothing if old and new are equal.
Parameters:
propertyName - the name of the property that changed
oldVal - the old value
newVal - the new value

firePropertyChange

public void firePropertyChange(String propertyName,
                               Object oldVal,
                               Object newVal)
Fire a PropertyChangeEvent containing the old and new values of the property to all the global listeners, and to all the listeners for the specified property name. This does nothing if old and new are non-null and equal.
Parameters:
propertyName - the name of the property that changed
oldVal - the old value
newVal - the new value

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners()
Returns an array of all registered property change listeners. Those that were registered under a name will be wrapped in a PropertyChangeListenerProxy, so you must check whether the listener is an instance of the proxy class in order to see what name the real listener is registered under. If there are no registered listeners, this returns an empty array.
Returns:
the array of registered listeners
Since:
1.4

getPropertyChangeListeners

public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)
Returns an array of all property change listeners registered under the given property name. If there are no registered listeners, or propertyName is null, this returns an empty array.
Returns:
the array of registered listeners
Since:
1.4

hasListeners

public boolean hasListeners(String propertyName)
Tell whether the specified property is being listened on or not. This will only return true if there are listeners on all properties or if there is a listener specifically on this property.
Parameters:
propertyName - the property that may be listened on
Returns:
whether the property is being listened on

removePropertyChangeListener

public void removePropertyChangeListener(PropertyChangeListener l)
Removes a PropertyChangeListener from the list of global listeners. If any specific properties are being listened on, they must be deregistered by themselves; this will only remove the general listener to all properties. If add() has been called multiple times for a particular listener, remove() will have to be called the same number of times to deregister it. This method will unwrap a PropertyChangeListenerProxy, removing the underlying delegate from the named property list.
Parameters:
l - the listener to remove

removePropertyChangeListener

public void removePropertyChangeListener(String propertyName,
                                         PropertyChangeListener l)
Removes a PropertyChangeListener from listening to a specific property. If add() has been called multiple times for a particular listener on a property, remove() will have to be called the same number of times to deregister it. This method will unwrap a PropertyChangeListenerProxy, removing the underlying delegate from the named property list if the names match.
Parameters:
propertyName - the property to stop listening on
l - the listener to remove
Throws:
NullPointerException - if propertyName is null

PropertyChangeSupport.java -- support to manage property change listeners Copyright (C) 1998, 1999, 2000, 2002, 2005, 2006 Free Software Foundation, Inc. This file is part of GNU Classpath. GNU Classpath is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. GNU Classpath is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with GNU Classpath; see the file COPYING. If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. Linking this library statically or dynamically with other modules is making a combined work based on this library. Thus, the terms and conditions of the GNU General Public License cover the whole combination. As a special exception, the copyright holders of this library give you permission to link this library with independent modules to produce an executable, regardless of the license terms of these independent modules, and to copy and distribute the resulting executable under terms of your choice, provided that you also meet, for each linked independent module, the terms and conditions of the license of that module. An independent module is a module which is not derived from or based on this library. If you modify this library, you may extend this exception to your version of the library, but you are not obligated to do so. If you do not wish to do so, delete this exception statement from your version.