Top Description Fields Constructors Methods
EDU.oswego.cs.dl.util.concurrent

public Class PropertyChangeMulticaster

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.beans.PropertyChangeListener, .PropertyChangeEvent, java.util.HashMap, java.io.Serializable, .ObjectOutputStream, .ObjectInputStream, .IOException
This class is interoperable with java.beans.PropertyChangeSupport, but relies on a streamlined copy-on-write scheme similar to that used in CopyOnWriteArrayList. This leads to much better performance in most event-intensive programs. It also adheres to clarified semantics of add and remove operations.

Sample usage. 

class Thing {
  protected Color myColor = Color.red; // an example property

  protected PropertyChangeMulticaster listeners =
    new PropertyChangeMulticaster(this);

  // registration methods, including:
  void addListener(PropertyChangeListener l) {
    // Use the `ifAbsent' version to avoid duplicate notifications
    listeners.addPropertyChangeListenerIfAbsent(l);
  }

 public synchronized Color getColor() { // accessor
   return myColor;
 }

  // internal synchronized state change method; returns old value
  protected synchronized Color assignColor(Color newColor) { 
    Color oldColor = myColor;
    myColor = newColor; 
    return oldColor;
  }

  public void setColor(Color newColor) {
    // atomically change state
    Color oldColor = assignColor(newColor);
    // broadcast change notification without holding synch lock
    listeners.firePropertyChange("color", oldColor, newColor);
  }
}
See Also
Introduction to this package.

Field Summary

Modifier and TypeField and Description
protected HashMap<K, V>
children

HashMap for managing listeners for specific properties.

protected transient PropertyChangeListener[]
listeners

The array of listeners.

protected final Object
source

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

Constructor Summary

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

Constructs a PropertyChangeMulticaster object.

Method Summary

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

Add a VetoableChangeListener 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.

public synchronized void
addPropertyChangeListenerIfAbsent(PropertyChangeListener
The PropertyChangeListener to be added
listener)

Add a PropertyChangeListener to the listener list if it is not already present.

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

Add a PropertyChangeListener for a specific property, if it is not already registered.

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)

Report a bound property update to any registered listeners.

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)

Report an int bound property update to any registered listeners.

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)

Report a boolean bound property update to any registered listeners.

public void
firePropertyChange(PropertyChangeEvent
The PropertyChangeEvent object.
evt)

Fire an existing PropertyChangeEvent to any registered listeners.

protected synchronized PropertyChangeMulticaster
getChild(String propertyName)

Return the child associated with property, or null if no such

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.

protected void
multicast(PropertyChangeEvent evt)

Helper method to relay evt to all listeners.

private void
readObject(ObjectInputStream s)

public synchronized 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 synchronized void
writeObject(ObjectOutputStream s)

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

childrenback to summary
protected HashMap<K, V> children

HashMap for managing listeners for specific properties. Maps property names to PropertyChangeMulticaster objects.

listenersback to summary
protected transient PropertyChangeListener[] listeners

The array of listeners. Copied on each update

sourceback to summary
protected final Object source

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

Constructor Detail

PropertyChangeMulticasterback to summary
public PropertyChangeMulticaster(Object sourceBean)

Constructs a PropertyChangeMulticaster object.

Parameters
sourceBean:Object

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

Exceptions
NullPointerException:
if sourceBean is null

Method Detail

addPropertyChangeListenerback to summary
public synchronized void addPropertyChangeListener(PropertyChangeListener listener)

Add a VetoableChangeListener to the listener list. The listener is registered for all properties. If the listener is added multiple times, it will receive multiple change notifications upon any firePropertyChange

Parameters
listener:PropertyChangeListener

The PropertyChangeListener to be added

Exceptions
NullPointerException:
If listener is null
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. However, if a listener is registered both for all properties and a specific property, it will receive multiple notifications upon changes to that property.

Parameters
propertyName:String

The name of the property to listen on.

listener:PropertyChangeListener

The PropertyChangeListener to be added

Exceptions
NullPointerException:
If listener is null
addPropertyChangeListenerIfAbsentback to summary
public synchronized void addPropertyChangeListenerIfAbsent(PropertyChangeListener listener)

Add a PropertyChangeListener to the listener list if it is not already present. The listener is registered for all properties. The operation maintains Set semantics: If the listener is already registered, the operation has no effect.

Parameters
listener:PropertyChangeListener

The PropertyChangeListener to be added

Exceptions
NullPointerException:
If listener is null
addPropertyChangeListenerIfAbsentback to summary
public void addPropertyChangeListenerIfAbsent(String propertyName, PropertyChangeListener listener)

Add a PropertyChangeListener for a specific property, if it is not already registered. The listener will be invoked only when a call on firePropertyChange names that specific property.

Parameters
propertyName:String

The name of the property to listen on.

listener:PropertyChangeListener

The PropertyChangeListener to be added

Exceptions
NullPointerException:
If listener is null
firePropertyChangeback to summary
public void firePropertyChange(String propertyName, Object oldValue, Object newValue)

Report a bound property update to any registered listeners. No event is fired if old and new are equal and non-null.

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)

Report an int bound property update to any registered listeners. No event is fired if old and new are equal and non-null.

This is merely a convenience wrapper around the more general firePropertyChange method that takes Object values.

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.

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

Report a boolean bound property update to any registered listeners. No event is fired if old and new are equal and non-null.

This is merely a convenience wrapper around the more general firePropertyChange method that takes Object values.

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.

firePropertyChangeback to summary
public void firePropertyChange(PropertyChangeEvent evt)

Fire an existing PropertyChangeEvent to any registered listeners. No event is fired if the given event's old and new values are equal and non-null.

Parameters
evt:PropertyChangeEvent

The PropertyChangeEvent object.

getChildback to summary
protected synchronized PropertyChangeMulticaster getChild(String propertyName)

Return the child associated with property, or null if no such

hasListenersback to summary
public boolean hasListeners(String propertyName)

Check if there are any listeners for a specific property. If propertyName is null, return whether there are any listeners at all.

Parameters
propertyName:String

the property name.

Returns:boolean

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

multicastback to summary
protected void multicast(PropertyChangeEvent evt)

Helper method to relay evt to all listeners. Called by all public firePropertyChange methods.

readObjectback to summary
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException
removePropertyChangeListenerback to summary
public synchronized void removePropertyChangeListener(PropertyChangeListener listener)

Remove a PropertyChangeListener from the listener list. It removes at most one occurrence of the given listener. If the listener was added multiple times it must be removed mulitple times. This removes a PropertyChangeListener that was registered for all properties, and has no effect if registered for only one or more specified properties.

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. Affects only the given property. If the listener is also registered for all properties, then it will continue to be registered for them.

Parameters
propertyName:String

The name of the property that was listened on.

listener:PropertyChangeListener

The PropertyChangeListener to be removed

writeObjectback to summary
private synchronized void writeObject(ObjectOutputStream s) throws IOException
Serial data
Null terminated list of PropertyChangeListeners.

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