/Users/richardallenbair/Documents/Source/Projects/nonsense/swingx/src/beaninfo/JavaBean_API.java |
/* * $Id: JavaBean_API.html 1316 2006-08-10 22:46:55Z rbair $ * * Copyright 2004 Sun Microsystems, Inc., 4150 Network Circle, * Santa Clara, California 95054, U.S.A. All rights reserved. * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public * License as published by the Free Software Foundation; either * version 2.1 of the License, or (at your option) any later version. * * This library 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 * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */ package org.jdesktop.swingx; import java.beans.PropertyChangeEvent; import java.beans.PropertyChangeListener; import java.beans.PropertyChangeSupport; /** * <p>A convenience class from which to extend all non-visual JavaBeans. It * manages the PropertyChange notification system, making it relatively trivial * to add support for property change events in getters/setters.</p> * * <p>Here is a simple example bean that contains one property, foo, and the * proper pattern for implementing property change notification: * <pre><code> * public class ABean extends JavaBean { * private String foo; * * public void setFoo(String newFoo) { * String old = getFoo(); * this.foo = newFoo; * firePropertyChange("foo", old, getFoo()); * } * * public String getFoo() { * return foo; * } * } * </code></pre></p> * * <p>You will notice that "getFoo()" is used in the setFoo method rather than * accessing "foo" directly for the gets. This is done intentionally so that if * a subclass overrides getFoo() to return, for instance, a constant value the * property change notification system will continue to work properly.</p> * * <p>The firePropertyChange method takes into account the old value and the new * value. Only if the two differ will it fire a property change event. So you can * be assured from the above code fragment that a property change event will only * occur if old is indeed different from getFoo()</p> * * @author rbair */ public class JavaBean { /** Creates a new instance of JavaBean */ protected JavaBean(); /** * 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 <code>listener</code> is null, no exception is thrown and no action * is taken. * * @param listener The PropertyChangeListener to be added */ public void addPropertyChangeListener(PropertyChangeListener listener); /** * Remove a PropertyChangeListener from the listener list. * This removes a PropertyChangeListener that was registered * for all properties. * If <code>listener</code> was added more than once to the same event * source, it will be notified one less time after being removed. * If <code>listener</code> 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); /** * Returns an array of all the listeners that were added to the * PropertyChangeSupport object with addPropertyChangeListener(). * <p> * If some listeners have been added with a named property, then * the returned array will be a mixture of PropertyChangeListeners * and <code>PropertyChangeListenerProxy</code>s. If the calling * method is interested in distinguishing the listeners then it must * test each element to see if it's a * <code>PropertyChangeListenerProxy</code>, perform the cast, and examine * the parameter. * * <pre> * 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" * } * } * } *</pre> * * @see java.beans.PropertyChangeListenerProxy * @return all of the <code>PropertyChangeListeners</code> added or an * empty array if no listeners have been added */ public PropertyChangeListener[] getPropertyChangeListeners(); /** * 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 <code>propertyName</code> or <code>listener</code> 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); /** * Remove a PropertyChangeListener for a specific property. * If <code>listener</code> 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 <code>propertyName</code> is null, no exception is thrown and no * action is taken. * If <code>listener</code> 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); /** * 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 <code>PropertyChangeListeners</code> associated with * the named property. If no such listeners have been added, * or if <code>propertyName</code> is null, an empty array is * returned. */ public PropertyChangeListener[] getPropertyChangeListeners(String propertyName); /** * Report a bound property update to any registered listeners. * No event is fired if old and new are equal and non-null. * * <p> * This is merely a convenience wrapper around the more general * firePropertyChange method that takes {@code * PropertyChangeEvent} value. * * @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); /** * Report an int bound property update to any registered listeners. * No event is fired if old and new are equal. * <p> * This is merely a convenience wrapper around the more general * firePropertyChange method that takes Object values. * * @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); /** * Report a boolean bound property update to any registered listeners. * No event is fired if old and new are equal. * <p> * This is merely a convenience wrapper around the more general * firePropertyChange method that takes Object values. * * @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); /** * 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. * @param evt The PropertyChangeEvent object. */ public void firePropertyChange(PropertyChangeEvent evt); /** * Report a bound indexed property update to any registered * listeners. * <p> * No event is fired if old and new values are equal * and non-null. * * <p> * This is merely a convenience wrapper around the more general * firePropertyChange method that takes {@code PropertyChangeEvent} value. * * @param propertyName The programmatic name of the property that * was changed. * @param index index of the property element that was changed. * @param oldValue The old value of the property. * @param newValue The new value of the property. */ public void fireIndexedPropertyChange(String propertyName, int index, Object oldValue, Object newValue); /** * Report an <code>int</code> bound indexed property update to any registered * listeners. * <p> * No event is fired if old and new values are equal. * <p> * This is merely a convenience wrapper around the more general * fireIndexedPropertyChange method which takes Object values. * * @param propertyName The programmatic name of the property that * was changed. * @param index index of the property element that was changed. * @param oldValue The old value of the property. * @param newValue The new value of the property. */ public void fireIndexedPropertyChange(String propertyName, int index, int oldValue, int newValue); /** * Report a <code>boolean</code> bound indexed property update to any * registered listeners. * <p> * No event is fired if old and new values are equal. * <p> * This is merely a convenience wrapper around the more general * fireIndexedPropertyChange method which takes Object values. * * @param propertyName The programmatic name of the property that * was changed. * @param index index of the property element that was changed. * @param oldValue The old value of the property. * @param newValue The new value of the property. */ public void fireIndexedPropertyChange(String propertyName, int index, boolean oldValue, boolean newValue); /** * Check if there are any listeners for a specific property, including * those registered on all properties. If <code>propertyName</code> * 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); }