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