/* * Copyright (c) 1996, 2008, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code 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 * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.beans; import java.io.Serializable; import java.io.ObjectStreamField; import java.io.ObjectOutputStream; import java.io.ObjectInputStream; import java.io.IOException; import java.util.Hashtable; import java.util.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 * {@link PropertyChangeEvent}s 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 {@link PropertyChangeListener} can be registered for all properties * or for a property specified by name. *

* Here is an example of {@code 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 {@code 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. * * @see VetoableChangeSupport */ public class PropertyChangeSupport implements Serializable { private PropertyChangeListenerMap map = new PropertyChangeListenerMap(); /** * Constructs a PropertyChangeSupport object. * * @param sourceBean The bean to be given as the source for any events. */ public PropertyChangeSupport(Object sourceBean) { if (sourceBean == null) { throw new NullPointerException(); } source = sourceBean; } /** * 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. * * @param listener The PropertyChangeListener to be added */ public void addPropertyChangeListener(PropertyChangeListener listener) { if (listener == null) { return; } if (listener instanceof PropertyChangeListenerProxy) { PropertyChangeListenerProxy proxy = (PropertyChangeListenerProxy)listener; // Call two argument add method. addPropertyChangeListener(proxy.getPropertyName(), proxy.getListener()); } else { this.map.add(null, 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. * * @param listener The PropertyChangeListener to be removed */ public void removePropertyChangeListener(PropertyChangeListener listener) { if (listener == null) { return; } if (listener instanceof PropertyChangeListenerProxy) { PropertyChangeListenerProxy proxy = (PropertyChangeListenerProxy)listener; // Call two argument remove method. removePropertyChangeListener(proxy.getPropertyName(), proxy.getListener()); } else { this.map.remove(null, listener); } } /** * 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"
     *     }
     *   }
     * }
     *
* * @see PropertyChangeListenerProxy * @return all of the PropertyChangeListeners added or an * empty array if no listeners have been added * @since 1.4 */ public PropertyChangeListener[] getPropertyChangeListeners() { return this.map.getListeners(); } /** * 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. * * @param propertyName The name of the property to listen on. * @param listener The PropertyChangeListener to be added */ public void addPropertyChangeListener( String propertyName, PropertyChangeListener listener) { if (listener == null || propertyName == null) { return; } listener = this.map.extract(listener); if (listener != null) { this.map.add(propertyName, 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. * * @param propertyName The name of the property that was listened on. * @param listener The PropertyChangeListener to be removed */ public void removePropertyChangeListener( String propertyName, PropertyChangeListener listener) { if (listener == null || propertyName == null) { return; } listener = this.map.extract(listener); if (listener != null) { this.map.remove(propertyName, listener); } } /** * Returns an array of all the listeners which have been associated * with the named property. * * @param propertyName The name of the property being listened to * @return 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 */ public PropertyChangeListener[] getPropertyChangeListeners(String propertyName) { return this.map.getListeners(propertyName); } /** * 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 * {@link #firePropertyChange(PropertyChangeEvent)} method. * * @param propertyName the programmatic name of the property that was changed * @param oldValue the old value of the property * @param newValue the new value of the property */ public void firePropertyChange(String propertyName, Object oldValue, Object newValue) { if (oldValue == null || newValue == null || !oldValue.equals(newValue)) { firePropertyChange(new PropertyChangeEvent(this.source, propertyName, oldValue, 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 * {@link #firePropertyChange(String, Object, Object)} method. * * @param propertyName the programmatic name of the property that was changed * @param oldValue the old value of the property * @param newValue the new value of the property */ public void firePropertyChange(String propertyName, int oldValue, int newValue) { if (oldValue != newValue) { firePropertyChange(propertyName, Integer.valueOf(oldValue), Integer.valueOf(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 * {@link #firePropertyChange(String, Object, Object)} method. * * @param propertyName the programmatic name of the property that was changed * @param oldValue the old value of the property * @param newValue the new value of the property */ public void firePropertyChange(String propertyName, boolean oldValue, boolean newValue) { if (oldValue != newValue) { firePropertyChange(propertyName, Boolean.valueOf(oldValue), Boolean.valueOf(newValue)); } } /** * 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. * * @param event the {@code PropertyChangeEvent} to be fired */ public void firePropertyChange(PropertyChangeEvent event) { Object oldValue = event.getOldValue(); Object newValue = event.getNewValue(); if (oldValue == null || newValue == null || !oldValue.equals(newValue)) { String name = event.getPropertyName(); PropertyChangeListener[] common = this.map.get(null); PropertyChangeListener[] named = (name != null) ? this.map.get(name) : null; fire(common, event); fire(named, event); } } private static void fire(PropertyChangeListener[] listeners, PropertyChangeEvent event) { if (listeners != null) { for (PropertyChangeListener listener : listeners) { listener.propertyChange(event); } } } /** * 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 * {@link #firePropertyChange(PropertyChangeEvent)} method. * * @param propertyName the programmatic name of the property that was changed * @param index the index of the property element that was changed * @param oldValue the old value of the property * @param newValue the new value of the property * @since 1.5 */ public void fireIndexedPropertyChange(String propertyName, int index, Object oldValue, Object newValue) { if (oldValue == null || newValue == null || !oldValue.equals(newValue)) { firePropertyChange(new IndexedPropertyChangeEvent(source, propertyName, oldValue, newValue, index)); } } /** * 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 * {@link #fireIndexedPropertyChange(String, int, Object, Object)} method. * * @param propertyName the programmatic name of the property that was changed * @param index the index of the property element that was changed * @param oldValue the old value of the property * @param newValue the new value of the property * @since 1.5 */ public void fireIndexedPropertyChange(String propertyName, int index, int oldValue, int newValue) { if (oldValue != newValue) { fireIndexedPropertyChange(propertyName, index, Integer.valueOf(oldValue), Integer.valueOf(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 * {@link #fireIndexedPropertyChange(String, int, Object, Object)} method. * * @param propertyName the programmatic name of the property that was changed * @param index the index of the property element that was changed * @param oldValue the old value of the property * @param newValue the new value of the property * @since 1.5 */ public void fireIndexedPropertyChange(String propertyName, int index, boolean oldValue, boolean newValue) { if (oldValue != newValue) { fireIndexedPropertyChange(propertyName, index, Boolean.valueOf(oldValue), Boolean.valueOf(newValue)); } } /** * 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. * * @param propertyName the property name. * @return true if there are one or more listeners for the given property */ public boolean hasListeners(String propertyName) { return this.map.hasListeners(propertyName); } /** * @serialData Null terminated list of PropertyChangeListeners. *

* At serialization time we skip non-serializable listeners and * only serialize the serializable listeners. */ private void writeObject(ObjectOutputStream s) throws IOException { Hashtable children = null; PropertyChangeListener[] listeners = null; synchronized (this.map) { for (Entry entry : this.map.getEntries()) { String property = entry.getKey(); if (property == null) { listeners = entry.getValue(); } else { if (children == null) { children = new Hashtable(); } PropertyChangeSupport pcs = new PropertyChangeSupport(this.source); pcs.map.set(null, entry.getValue()); children.put(property, pcs); } } } ObjectOutputStream.PutField fields = s.putFields(); fields.put("children", children); fields.put("source", this.source); fields.put("propertyChangeSupportSerializedDataVersion", 2); s.writeFields(); if (listeners != null) { for (PropertyChangeListener l : listeners) { if (l instanceof Serializable) { s.writeObject(l); } } } s.writeObject(null); } private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException { this.map = new PropertyChangeListenerMap(); ObjectInputStream.GetField fields = s.readFields(); Hashtable children = (Hashtable) fields.get("children", null); this.source = fields.get("source", null); fields.get("propertyChangeSupportSerializedDataVersion", 2); Object listenerOrNull; while (null != (listenerOrNull = s.readObject())) { this.map.add(null, (PropertyChangeListener)listenerOrNull); } if (children != null) { for (Entry entry : children.entrySet()) { for (PropertyChangeListener listener : entry.getValue().getPropertyChangeListeners()) { this.map.add(entry.getKey(), listener); } } } } /** * The object to be provided as the "source" for any generated events. */ private Object source; /** * @serialField children Hashtable * @serialField source Object * @serialField propertyChangeSupportSerializedDataVersion int */ private static final ObjectStreamField[] serialPersistentFields = { new ObjectStreamField("children", Hashtable.class), new ObjectStreamField("source", Object.class), new ObjectStreamField("propertyChangeSupportSerializedDataVersion", Integer.TYPE) }; /** * Serialization version ID, so we're compatible with JDK 1.1 */ static final long serialVersionUID = 6401253773779951803L; /** * This is a {@link ChangeListenerMap ChangeListenerMap} implementation * that works with {@link PropertyChangeListener PropertyChangeListener} objects. */ private static final class PropertyChangeListenerMap extends ChangeListenerMap { private static final PropertyChangeListener[] EMPTY = {}; /** * Creates an array of {@link PropertyChangeListener PropertyChangeListener} objects. * This method uses the same instance of the empty array * when {@code length} equals {@code 0}. * * @param length the array length * @return an array with specified length */ @Override protected PropertyChangeListener[] newArray(int length) { return (0 < length) ? new PropertyChangeListener[length] : EMPTY; } /** * Creates a {@link PropertyChangeListenerProxy PropertyChangeListenerProxy} * object for the specified property. * * @param name the name of the property to listen on * @param listener the listener to process events * @return a {@code PropertyChangeListenerProxy} object */ @Override protected PropertyChangeListener newProxy(String name, PropertyChangeListener listener) { return new PropertyChangeListenerProxy(name, listener); } } }