APIdia Launch Partner
Top Description Inners Fields Constructors Methods
java.beans

public Class PropertyChangeSupport

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Known Direct Subclasses
javax.swing.SwingWorker.SwingWorkerPropertyChangeSupport, javax.swing.event.SwingPropertyChangeSupport, java.awt.Toolkit.DesktopPropertyChangeSupport
Imports
java.io.IOException, .ObjectInputStream, .ObjectOutputStream, .ObjectStreamField, .Serial, .Serializable, java.util.Hashtable, .Map.Entry
This is a utility class that can be used by beans that support bound properties. It manages a list of listeners and dispatches PropertyChangeEvents to them. You can use an instance of this class as a member field of your bean and delegate these types of work to it. The PropertyChangeListener can be registered for all properties or for a property specified by name.

Here is an example of PropertyChangeSupport usage that follows the rules and recommendations laid out in the JavaBeans specification: 

public class MyBean {
    private final PropertyChangeSupport pcs = new PropertyChangeSupport(this);

    public void addPropertyChangeListener(PropertyChangeListener listener) {
        this.pcs.addPropertyChangeListener(listener);
    }

    public void removePropertyChangeListener(PropertyChangeListener listener) {
        this.pcs.removePropertyChangeListener(listener);
    }

    private String value;

    public String getValue() {
        return this.value;
    }

    public void setValue(String newValue) {
        String oldValue = this.value;
        this.value = newValue;
        this.pcs.firePropertyChange("value", oldValue, newValue);
    }

    [...]
}

A PropertyChangeSupport instance is thread-safe.

This class is serializable. When it is serialized it will save (and restore) any listeners that are themselves serializable. Any non-serializable listeners will be skipped during serialization.

Since
1.1
See Also
VetoableChangeSupport

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
PropertyChangeSupport.PropertyChangeListenerMap

This is a ChangeListenerMap implementation that works with PropertyChangeListener objects.

Field Summary

Modifier and TypeField and Description
private PropertyChangeSupport.PropertyChangeListenerMap
map

private static final ObjectStreamField[]
serialPersistentFields

private static final long
serialVersionUID

Use serialVersionUID from JDK 1.1 for interoperability.

private Object
source

The object to be provided as the "source" for any generated events.

Constructor Summary

AccessConstructor and Description
public
PropertyChangeSupport(Object
The bean to be given as the source for any events.
sourceBean)

Constructs a PropertyChangeSupport object.

Method Summary

Modifier and TypeMethod and Description
public void
addPropertyChangeListener(PropertyChangeListener
The PropertyChangeListener to be added
listener)

Add a PropertyChangeListener to the listener list.

public void
addPropertyChangeListener(String
The name of the property to listen on.
propertyName, PropertyChangeListener
The PropertyChangeListener to be added
listener)

Add a PropertyChangeListener for a specific property.

private static void
fire(PropertyChangeListener[] listeners, PropertyChangeEvent event)

public void
fireIndexedPropertyChange(String
the programmatic name of the property that was changed
propertyName, int
the index of the property element that was changed
index, Object
the old value of the property
oldValue, Object
the new value of the property
newValue)

Reports a bound indexed property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
fireIndexedPropertyChange(String
the programmatic name of the property that was changed
propertyName, int
the index of the property element that was changed
index, int
the old value of the property
oldValue, int
the new value of the property
newValue)

Reports an integer bound indexed property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
fireIndexedPropertyChange(String
the programmatic name of the property that was changed
propertyName, int
the index of the property element that was changed
index, boolean
the old value of the property
oldValue, boolean
the new value of the property
newValue)

Reports a boolean bound indexed property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
firePropertyChange(String
the programmatic name of the property that was changed
propertyName, Object
the old value of the property
oldValue, Object
the new value of the property
newValue)

Reports a bound property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
firePropertyChange(String
the programmatic name of the property that was changed
propertyName, int
the old value of the property
oldValue, int
the new value of the property
newValue)

Reports an integer bound property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
firePropertyChange(String
the programmatic name of the property that was changed
propertyName, boolean
the old value of the property
oldValue, boolean
the new value of the property
newValue)

Reports a boolean bound property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
firePropertyChange(PropertyChangeEvent
the PropertyChangeEvent to be fired
event)

Fires a property change event to listeners that have been registered to track updates of all properties or a property with the specified name.

public PropertyChangeListener[]

Returns:

all of the PropertyChangeListeners added or an empty array if no listeners have been added
getPropertyChangeListeners()

Returns an array of all the listeners that were added to the PropertyChangeSupport object with addPropertyChangeListener().

public PropertyChangeListener[]

Returns:

all of the PropertyChangeListeners associated with the named property. If no such listeners have been added, or if propertyName is null, an empty array is returned.
getPropertyChangeListeners(String
The name of the property being listened to
propertyName)

Returns an array of all the listeners which have been associated with the named property.

public boolean

Returns:

true if there are one or more listeners for the given property
hasListeners(String
the property name.
propertyName)

Check if there are any listeners for a specific property, including those registered on all properties.

private void
readObject(ObjectInputStream
the ObjectInputStream to read
s)

Reads the ObjectInputStream.

public void
removePropertyChangeListener(PropertyChangeListener
The PropertyChangeListener to be removed
listener)

Remove a PropertyChangeListener from the listener list.

public void
removePropertyChangeListener(String
The name of the property that was listened on.
propertyName, PropertyChangeListener
The PropertyChangeListener to be removed
listener)

Remove a PropertyChangeListener for a specific property.

private void
writeObject(ObjectOutputStream
the ObjectOutputStream to write
s)

Writes serializable fields to stream.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

mapback to summary
private PropertyChangeSupport.PropertyChangeListenerMap map
serialPersistentFieldsback to summary
private static final ObjectStreamField[] serialPersistentFields
Annotations
@Serial
Serial Fields:
children:Hashtable
The list of PropertyChangeListeners
source:Object
The object to be provided as the "source" for any generated events
propertyChangeSupportSerializedDataVersion:int
The version
serialVersionUIDback to summary
private static final long serialVersionUID

Use serialVersionUID from JDK 1.1 for interoperability.

Annotations
@Serial
sourceback to summary
private Object source

The object to be provided as the "source" for any generated events.

Constructor Detail

PropertyChangeSupportback to summary
public PropertyChangeSupport(Object sourceBean)

Constructs a PropertyChangeSupport object.

Parameters
sourceBean:Object

The bean to be given as the source for any events.

Method Detail

addPropertyChangeListenerback to summary
public void addPropertyChangeListener(PropertyChangeListener listener)

Add a PropertyChangeListener to the listener list. The listener is registered for all properties. The same listener object may be added more than once, and will be called as many times as it is added. If listener is null, no exception is thrown and no action is taken.

Parameters
listener:PropertyChangeListener

The PropertyChangeListener to be added

addPropertyChangeListenerback to summary
public void addPropertyChangeListener(String propertyName, PropertyChangeListener listener)

Add a PropertyChangeListener for a specific property. The listener will be invoked only when a call on firePropertyChange names that specific property. The same listener object may be added more than once. For each property, the listener will be invoked the number of times it was added for that property. If propertyName or listener is null, no exception is thrown and no action is taken.

Parameters
propertyName:String

The name of the property to listen on.

listener:PropertyChangeListener

The PropertyChangeListener to be added

Since
1.2
fireback to summary
private static void fire(PropertyChangeListener[] listeners, PropertyChangeEvent event)
fireIndexedPropertyChangeback to summary
public void fireIndexedPropertyChange(String propertyName, int index, Object oldValue, Object newValue)

Reports a bound indexed property update to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if old and new values are equal and non-null.

This is merely a convenience wrapper around the more general firePropertyChange(PropertyChangeEvent) method.

Parameters
propertyName:String

the programmatic name of the property that was changed

index:int

the index of the property element that was changed

oldValue:Object

the old value of the property

newValue:Object

the new value of the property

Since
1.5
fireIndexedPropertyChangeback to summary
public void fireIndexedPropertyChange(String propertyName, int index, int oldValue, int newValue)

Reports an integer bound indexed property update to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if old and new values are equal.

This is merely a convenience wrapper around the more general fireIndexedPropertyChange(String, int, Object, Object) method.

Parameters
propertyName:String

the programmatic name of the property that was changed

index:int

the index of the property element that was changed

oldValue:int

the old value of the property

newValue:int

the new value of the property

Since
1.5
fireIndexedPropertyChangeback to summary
public void fireIndexedPropertyChange(String propertyName, int index, boolean oldValue, boolean newValue)

Reports a boolean bound indexed property update to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if old and new values are equal.

This is merely a convenience wrapper around the more general fireIndexedPropertyChange(String, int, Object, Object) method.

Parameters
propertyName:String

the programmatic name of the property that was changed

index:int

the index of the property element that was changed

oldValue:boolean

the old value of the property

newValue:boolean

the new value of the property

Since
1.5
firePropertyChangeback to summary
public void firePropertyChange(String propertyName, Object oldValue, Object newValue)

Reports a bound property update to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if old and new values are equal and non-null.

This is merely a convenience wrapper around the more general firePropertyChange(PropertyChangeEvent) method.

Parameters
propertyName:String

the programmatic name of the property that was changed

oldValue:Object

the old value of the property

newValue:Object

the new value of the property

firePropertyChangeback to summary
public void firePropertyChange(String propertyName, int oldValue, int newValue)

Reports an integer bound property update to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if old and new values are equal.

This is merely a convenience wrapper around the more general firePropertyChange(String, Object, Object) method.

Parameters
propertyName:String

the programmatic name of the property that was changed

oldValue:int

the old value of the property

newValue:int

the new value of the property

Since
1.2
firePropertyChangeback to summary
public void firePropertyChange(String propertyName, boolean oldValue, boolean newValue)

Reports a boolean bound property update to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if old and new values are equal.

This is merely a convenience wrapper around the more general firePropertyChange(String, Object, Object) method.

Parameters
propertyName:String

the programmatic name of the property that was changed

oldValue:boolean

the old value of the property

newValue:boolean

the new value of the property

Since
1.2
firePropertyChangeback to summary
public void firePropertyChange(PropertyChangeEvent event)

Fires a property change event to listeners that have been registered to track updates of all properties or a property with the specified name.

No event is fired if the given event's old and new values are equal and non-null.

Parameters
event:PropertyChangeEvent

the PropertyChangeEvent to be fired

Since
1.2
getPropertyChangeListenersback to summary
public PropertyChangeListener[] getPropertyChangeListeners()

Returns an array of all the listeners that were added to the PropertyChangeSupport object with addPropertyChangeListener().

If some listeners have been added with a named property, then the returned array will be a mixture of PropertyChangeListeners and PropertyChangeListenerProxys. If the calling method is interested in distinguishing the listeners then it must test each element to see if it's a PropertyChangeListenerProxy, perform the cast, and examine the parameter. 

PropertyChangeListener[] listeners = bean.getPropertyChangeListeners();
for (int i = 0; i < listeners.length; i++) {
  if (listeners[i] instanceof PropertyChangeListenerProxy) {
    PropertyChangeListenerProxy proxy =
                   (PropertyChangeListenerProxy)listeners[i];
    if (proxy.getPropertyName().equals("foo")) {
      // proxy is a PropertyChangeListener which was associated
      // with the property named "foo"
    }
  }
}
Returns:PropertyChangeListener[]

all of the PropertyChangeListeners added or an empty array if no listeners have been added

Since
1.4
See Also
PropertyChangeListenerProxy
getPropertyChangeListenersback to summary
public PropertyChangeListener[] getPropertyChangeListeners(String propertyName)

Returns an array of all the listeners which have been associated with the named property.

Parameters
propertyName:String

The name of the property being listened to

Returns:PropertyChangeListener[]

all of the PropertyChangeListeners associated with the named property. If no such listeners have been added, or if propertyName is null, an empty array is returned.

Since
1.4
hasListenersback to summary
public boolean hasListeners(String propertyName)

Check if there are any listeners for a specific property, including those registered on all properties. If propertyName is null, only check for listeners registered on all properties.

Parameters
propertyName:String

the property name.

Returns:boolean

true if there are one or more listeners for the given property

Since
1.2
readObjectback to summary
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException

Reads the ObjectInputStream.

Parameters
s:ObjectInputStream

the ObjectInputStream to read

Annotations
@Serial
Exceptions
ClassNotFoundException:
if the class of a serialized object could not be found
IOException:
if an I/O error occurs
removePropertyChangeListenerback to summary
public void removePropertyChangeListener(PropertyChangeListener listener)

Remove a PropertyChangeListener from the listener list. This removes a PropertyChangeListener that was registered for all properties. If listener was added more than once to the same event source, it will be notified one less time after being removed. If listener is null, or was never added, no exception is thrown and no action is taken.

Parameters
listener:PropertyChangeListener

The PropertyChangeListener to be removed

removePropertyChangeListenerback to summary
public void removePropertyChangeListener(String propertyName, PropertyChangeListener listener)

Remove a PropertyChangeListener for a specific property. If listener was added more than once to the same event source for the specified property, it will be notified one less time after being removed. If propertyName is null, no exception is thrown and no action is taken. If listener is null, or was never added for the specified property, no exception is thrown and no action is taken.

Parameters
propertyName:String

The name of the property that was listened on.

listener:PropertyChangeListener

The PropertyChangeListener to be removed

Since
1.2
writeObjectback to summary
private void writeObject(ObjectOutputStream s) throws IOException

Writes serializable fields to stream.

Parameters
s:ObjectOutputStream

the ObjectOutputStream to write

Annotations
@Serial
Exceptions
IOException:
if an I/O error occurs
Serial data
Null terminated list of PropertyChangeListeners.

At serialization time we skip non-serializable listeners and only serialize the serializable listeners.

java.beans back to summary

private final Class PropertyChangeSupport.PropertyChangeListenerMap

extends ChangeListenerMap<PropertyChangeListener>
Class Inheritance
This is a ChangeListenerMap implementation that works with PropertyChangeListener objects.

Field Summary

Modifier and TypeField and Description
private static final PropertyChangeListener[]
EMPTY

Constructor Summary

AccessConstructor and Description
private
PropertyChangeListenerMap()

Method Summary

Modifier and TypeMethod and Description
public PropertyChangeListener
extract(PropertyChangeListener listener)

Implements abstract java.beans.ChangeListenerMap.extract.

Extracts a real listener from the proxy listener.

protected PropertyChangeListener[]

Returns:

an array with specified length
newArray(int
the array length
length)

Implements abstract java.beans.ChangeListenerMap.newArray.

Creates an array of PropertyChangeListener objects.

protected PropertyChangeListener

Returns:

a PropertyChangeListenerProxy object
newProxy(String
the name of the property to listen on
name, PropertyChangeListener
the listener to process events
listener)

Implements abstract java.beans.ChangeListenerMap.newProxy.

Creates a PropertyChangeListenerProxy object for the specified property.

Inherited from java.beans.ChangeListenerMap:
addgetgetEntriesgetListenersgetListenershasListenersremoveset

Field Detail

EMPTYback to summary
private static final PropertyChangeListener[] EMPTY

Constructor Detail

PropertyChangeListenerMapback to summary
private PropertyChangeListenerMap()

Method Detail

extractback to summary
public PropertyChangeListener extract(PropertyChangeListener listener)

Implements abstract java.beans.ChangeListenerMap.extract.

Doc from java.beans.ChangeListenerMap.extract.

Extracts a real listener from the proxy listener. It is necessary because default proxy class is not serializable.

Annotations
@Override
newArrayback to summary
protected PropertyChangeListener[] newArray(int length)

Implements abstract java.beans.ChangeListenerMap.newArray.

Creates an array of PropertyChangeListener objects. This method uses the same instance of the empty array when length equals 0.

Parameters
length:int

the array length

Returns:PropertyChangeListener[]

an array with specified length

Annotations
@Override
newProxyback to summary
protected PropertyChangeListener newProxy(String name, PropertyChangeListener listener)

Implements abstract java.beans.ChangeListenerMap.newProxy.

Creates a PropertyChangeListenerProxy object for the specified property.

Parameters
name:String

the name of the property to listen on

listener:PropertyChangeListener

the listener to process events

Returns:PropertyChangeListener

a PropertyChangeListenerProxy object

Annotations
@Override