Package EDU.oswego.cs.dl.util.concurrent

Class PropertyChangeMulticaster

  • All Implemented Interfaces:
    java.io.Serializable
    public class PropertyChangeMulticaster
extends java.lang.Object
implements java.io.Serializable
    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);
   }
 }

    [ Introduction to this package. ]

    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.util.HashMap children
      HashMap for managing listeners for specific properties.
      protected java.beans.PropertyChangeListener[] listeners
      The array of listeners.
      protected java.lang.Object source
      The object to be provided as the "source" for any generated events.

    • Constructor Summary

      Constructors 
      Constructor Description
      PropertyChangeMulticaster​(java.lang.Object sourceBean)
      Constructs a PropertyChangeMulticaster object.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addPropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Add a VetoableChangeListener to the listener list.
      void addPropertyChangeListener​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Add a PropertyChangeListener for a specific property.
      void addPropertyChangeListenerIfAbsent​(java.beans.PropertyChangeListener listener)
      Add a PropertyChangeListener to the listener list if it is not already present.
      void addPropertyChangeListenerIfAbsent​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Add a PropertyChangeListener for a specific property, if it is not already registered.
      void firePropertyChange​(java.beans.PropertyChangeEvent evt)
      Fire an existing PropertyChangeEvent to any registered listeners.
      void firePropertyChange​(java.lang.String propertyName, boolean oldValue, boolean newValue)
      Report a boolean bound property update to any registered listeners.
      void firePropertyChange​(java.lang.String propertyName, int oldValue, int newValue)
      Report an int bound property update to any registered listeners.
      void firePropertyChange​(java.lang.String propertyName, java.lang.Object oldValue, java.lang.Object newValue)
      Report a bound property update to any registered listeners.
      protected PropertyChangeMulticaster getChild​(java.lang.String propertyName)
      Return the child associated with property, or null if no such
      boolean hasListeners​(java.lang.String propertyName)
      Check if there are any listeners for a specific property.
      protected void multicast​(java.beans.PropertyChangeEvent evt)
      Helper method to relay evt to all listeners.
      void removePropertyChangeListener​(java.beans.PropertyChangeListener listener)
      Remove a PropertyChangeListener from the listener list.
      void removePropertyChangeListener​(java.lang.String propertyName, java.beans.PropertyChangeListener listener)
      Remove a PropertyChangeListener for a specific property.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • listeners

        protected transient java.beans.PropertyChangeListener[] listeners
        The array of listeners. Copied on each update

      • source

        protected final java.lang.Object source
        The object to be provided as the "source" for any generated events.

      • children

        protected java.util.HashMap children
        HashMap for managing listeners for specific properties. Maps property names to PropertyChangeMulticaster objects.

    • Constructor Detail

      • PropertyChangeMulticaster

        public PropertyChangeMulticaster​(java.lang.Object sourceBean)
        Constructs a PropertyChangeMulticaster object.
        Parameters:
        sourceBean - The bean to be given as the source for any events.
        Throws:
        java.lang.NullPointerException - if sourceBean is null

    • Method Detail

      • getChild

        protected PropertyChangeMulticaster getChild​(java.lang.String propertyName)
        Return the child associated with property, or null if no such

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.beans.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 - The PropertyChangeListener to be added
        Throws:
        java.lang.NullPointerException - If listener is null

      • addPropertyChangeListenerIfAbsent

        public void addPropertyChangeListenerIfAbsent​(java.beans.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 - The PropertyChangeListener to be added
        Throws:
        java.lang.NullPointerException - If listener is null

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.beans.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 - The PropertyChangeListener to be removed

      • addPropertyChangeListener

        public void addPropertyChangeListener​(java.lang.String propertyName,
                                      java.beans.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 - The name of the property to listen on.
        listener - The PropertyChangeListener to be added
        Throws:
        java.lang.NullPointerException - If listener is null

      • addPropertyChangeListenerIfAbsent

        public void addPropertyChangeListenerIfAbsent​(java.lang.String propertyName,
                                              java.beans.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 - The name of the property to listen on.
        listener - The PropertyChangeListener to be added
        Throws:
        java.lang.NullPointerException - If listener is null

      • removePropertyChangeListener

        public void removePropertyChangeListener​(java.lang.String propertyName,
                                         java.beans.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 - The name of the property that was listened on.
        listener - The PropertyChangeListener to be removed

      • multicast

        protected void multicast​(java.beans.PropertyChangeEvent evt)
        Helper method to relay evt to all listeners. Called by all public firePropertyChange methods.

      • firePropertyChange

        public void firePropertyChange​(java.lang.String propertyName,
                               java.lang.Object oldValue,
                               java.lang.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 - The programmatic name of the property that was changed.
        oldValue - The old value of the property.
        newValue - The new value of the property.

      • firePropertyChange

        public void firePropertyChange​(java.lang.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 - The programmatic name of the property that was changed.
        oldValue - The old value of the property.
        newValue - The new value of the property.

      • firePropertyChange

        public void firePropertyChange​(java.lang.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 - The programmatic name of the property that was changed.
        oldValue - The old value of the property.
        newValue - The new value of the property.

      • firePropertyChange

        public void firePropertyChange​(java.beans.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 - The PropertyChangeEvent object.

      • hasListeners

        public boolean hasListeners​(java.lang.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 - the property name.
        Returns:
        true if there are one or more listeners for the given property