1 /*

     2  * Copyright 2002-2007 Sun Microsystems, Inc.  All Rights Reserved.

     3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

     4  *

     5  * This code is free software; you can redistribute it and/or modify it

     6  * under the terms of the GNU General Public License version 2 only, as

     7  * published by the Free Software Foundation.  Sun designates this

     8  * particular file as subject to the "Classpath" exception as provided

     9  * by Sun in the LICENSE file that accompanied this code.

    10  *

    11  * This code is distributed in the hope that it will be useful, but WITHOUT

    12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

    13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

    14  * version 2 for more details (a copy is included in the LICENSE file that

    15  * accompanied this code).

    16  *

    17  * You should have received a copy of the GNU General Public License version

    18  * 2 along with this work; if not, write to the Free Software Foundation,

    19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

    20  *

    21  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

    22  * CA 95054 USA or visit www.sun.com if you need additional information or

    23  * have any questions.

    24  */

    25 package org.jdesktop.beans;

    26 

    27 import java.beans.PropertyChangeEvent;

    28 import java.beans.PropertyChangeListener;

    29 import java.beans.PropertyChangeSupport;

    30 import java.beans.PropertyVetoException;

    31 import java.beans.VetoableChangeListener;

    32 import java.beans.VetoableChangeSupport;

    33 

    34 /**

    35  * <p>A convenience class from which to extend all non-visual AbstractBeans. It

    36  * manages the PropertyChange notification system, making it relatively trivial

    37  * to add support for property change events in getters/setters.</p>

    38  *

    39  * <p>A non-visual java bean is a Java class that conforms to the AbstractBean

    40  * patterns to allow visual manipulation of the bean's properties and event

    41  * handlers at design-time.</p>

    42  *

    43  * <p>Here is a simple example bean that contains one property, foo, and the

    44  * proper pattern for implementing property change notification:

    45  * <pre><code>

    46  *  public class ABean extends AbstractBean {

    47  *    private String foo;

    48  *

    49  *    public void setFoo(String newFoo) {

    50  *      String old = getFoo();

    51  *      this.foo = newFoo;

    52  *      firePropertyChange("foo", old, getFoo());

    53  *    }

    54  *

    55  *    public String getFoo() {

    56  *      return foo;

    57  *    }

    58  *  }

    59  * </code></pre></p>

    60  *

    61  * <p>You will notice that "getFoo()" is used in the setFoo method rather than

    62  * accessing "foo" directly for the gets. This is done intentionally so that if

    63  * a subclass overrides getFoo() to return, for instance, a constant value the

    64  * property change notification system will continue to work properly.</p>

    65  *

    66  * <p>The firePropertyChange method takes into account the old value and the new

    67  * value. Only if the two differ will it fire a property change event. So you can

    68  * be assured from the above code fragment that a property change event will only

    69  * occur if old is indeed different from getFoo()</p>

    70  *

    71  * <p><code>AbstractBean</code> also supports {@link VetoablePropertyChange} events.

    72  * These events are similar to <code>PropertyChange</code> events, except a special

    73  * exception can be used to veto changing the property. For example, perhaps the

    74  * property is changing from "fred" to "red", but a listener deems that "red" is

    75  * unexceptable. In this case, the listener can fire a veto exception and the property must

    76  * remain "fred". For example:

    77  * <pre><code>

    78  *  public class ABean extends AbstractBean {

    79  *    private String foo;

    80  *

    81  *    public void setFoo(String newFoo) throws PropertyVetoException {

    82  *      String old = getFoo();

    83  *      this.foo = newFoo;

    84  *      fireVetoableChange("foo", old, getFoo());

    85  *    }

    86  *

    87  *    public String getFoo() {

    88  *      return foo;

    89  *    }

    90  *  }

    91  *

    92  *  public class Tester {

    93  *    public static void main(String... args) {

    94  *      try {

    95  *        ABean a = new ABean();

    96  *        a.setFoo("fred");

    97  *        a.addVetoableChangeListener(new VetoableChangeListener() {

    98  *          public void vetoableChange(PropertyChangeEvent evt) throws PropertyVetoException {

    99  *            if ("red".equals(evt.getNewValue()) {

   100  *              throw new PropertyVetoException("Cannot be red!", evt);

   101  *            }

   102  *          }

   103  *        }

   104  *        a.setFoo("red");

   105  *      } catch (Exception e) {

   106  *        e.printStackTrace(); // this will be executed

   107  *      }

   108  *    }

   109  *  }

   110  * </code></pre></p>

   111  *

   112  * @status REVIEWED

   113  * @author rbair

   114  */

   115 public abstract class AbstractBean {

   116     /**

   117      * Helper class that manages all the property change notification machinery.

   118      * PropertyChangeSupport cannot be extended directly because it requires

   119      * a bean in the constructor, and the "this" argument is not valid until

   120      * after super construction. Hence, delegation instead of extension

   121      */

   122     private transient PropertyChangeSupport pcs;

   123 

   124     /**

   125      * Helper class that manages all the veto property change notification machinery.

   126      */

   127     private transient VetoableChangeSupport vcs;

   128 

   129     /** Creates a new instance of AbstractBean */

   130     protected AbstractBean() {

   131         pcs = new PropertyChangeSupport(this);

   132         vcs = new VetoableChangeSupport(this);

   133     }

   134 

   135     /**

   136      * Creates a new instance of AbstractBean, using the supplied PropertyChangeSupport and

   137      * VetoableChangeSupport delegates. Neither of these may be null.

   138      */

   139     protected AbstractBean(PropertyChangeSupport pcs, VetoableChangeSupport vcs) {

   140         if (pcs == null) {

   141             throw new NullPointerException("PropertyChangeSupport must not be null");

   142         }

   143         if (vcs == null) {

   144             throw new NullPointerException("VetoableChangeSupport must not be null");

   145         }

   146 

   147         this.pcs = pcs;

   148         this.vcs = vcs;

   149     }

   150 

   151     /**

   152      * Add a PropertyChangeListener to the listener list.

   153      * The listener is registered for all properties.

   154      * The same listener object may be added more than once, and will be called

   155      * as many times as it is added.

   156      * If <code>listener</code> is null, no exception is thrown and no action

   157      * is taken.

   158      *

   159      * @param listener  The PropertyChangeListener to be added

   160      */

   161     public final void addPropertyChangeListener(PropertyChangeListener listener) {

   162         pcs.addPropertyChangeListener(listener);

   163     }

   164 

   165     /**

   166      * Remove a PropertyChangeListener from the listener list.

   167      * This removes a PropertyChangeListener that was registered

   168      * for all properties.

   169      * If <code>listener</code> was added more than once to the same event

   170      * source, it will be notified one less time after being removed.

   171      * If <code>listener</code> is null, or was never added, no exception is

   172      * thrown and no action is taken.

   173      *

   174      * @param listener  The PropertyChangeListener to be removed

   175      */

   176     public final void removePropertyChangeListener(PropertyChangeListener listener) {

   177         pcs.removePropertyChangeListener(listener);

   178     }

   179 

   180     /**

   181      * Returns an array of all the listeners that were added to the

   182      * PropertyChangeSupport object with addPropertyChangeListener().

   183      * <p>

   184      * If some listeners have been added with a named property, then

   185      * the returned array will be a mixture of PropertyChangeListeners

   186      * and <code>PropertyChangeListenerProxy</code>s. If the calling

   187      * method is interested in distinguishing the listeners then it must

   188      * test each element to see if it's a

   189      * <code>PropertyChangeListenerProxy</code>, perform the cast, and examine

   190      * the parameter.

   191      *

   192      * <pre>

   193      * PropertyChangeListener[] listeners = bean.getPropertyChangeListeners();

   194      * for (int i = 0; i < listeners.length; i++) {

   195      *   if (listeners[i] instanceof PropertyChangeListenerProxy) {

   196      *     PropertyChangeListenerProxy proxy =

   197      *                    (PropertyChangeListenerProxy)listeners[i];

   198      *     if (proxy.getPropertyName().equals("foo")) {

   199      *       // proxy is a PropertyChangeListener which was associated

   200      *       // with the property named "foo"

   201      *     }

   202      *   }

   203      * }

   204      *</pre>

   205      *

   206      * @see java.beans.PropertyChangeListenerProxy

   207      * @return all of the <code>PropertyChangeListeners</code> added or an

   208      *         empty array if no listeners have been added

   209      */

   210     public final PropertyChangeListener[] getPropertyChangeListeners() {

   211         return pcs.getPropertyChangeListeners();

   212     }

   213 

   214     /**

   215      * Add a PropertyChangeListener for a specific property.  The listener

   216      * will be invoked only when a call on firePropertyChange names that

   217      * specific property.

   218      * The same listener object may be added more than once.  For each

   219      * property,  the listener will be invoked the number of times it was added

   220      * for that property.

   221      * If <code>propertyName</code> or <code>listener</code> is null, no

   222      * exception is thrown and no action is taken.

   223      *

   224      * @param propertyName  The name of the property to listen on.

   225      * @param listener  The PropertyChangeListener to be added

   226      */

   227     public final void addPropertyChangeListener(String propertyName, PropertyChangeListener listener) {

   228         pcs.addPropertyChangeListener(propertyName, listener);

   229     }

   230 

   231     /**

   232      * Remove a PropertyChangeListener for a specific property.

   233      * If <code>listener</code> was added more than once to the same event

   234      * source for the specified property, it will be notified one less time

   235      * after being removed.

   236      * If <code>propertyName</code> is null,  no exception is thrown and no

   237      * action is taken.

   238      * If <code>listener</code> is null, or was never added for the specified

   239      * property, no exception is thrown and no action is taken.

   240      *

   241      * @param propertyName  The name of the property that was listened on.

   242      * @param listener  The PropertyChangeListener to be removed

   243      */

   244     public final void removePropertyChangeListener(String propertyName, PropertyChangeListener listener) {

   245         pcs.removePropertyChangeListener(propertyName, listener);

   246     }

   247 

   248     /**

   249      * Returns an array of all the listeners which have been associated

   250      * with the named property.

   251      *

   252      * @param propertyName  The name of the property being listened to

   253      * @return all of the <code>PropertyChangeListeners</code> associated with

   254      *         the named property.  If no such listeners have been added,

   255      *         or if <code>propertyName</code> is null, an empty array is

   256      *         returned.

   257      */

   258     public final PropertyChangeListener[] getPropertyChangeListeners(String propertyName) {

   259             return pcs.getPropertyChangeListeners(propertyName);

   260     }

   261 

   262     /**

   263      * Report a bound property update to any registered listeners.

   264      * No event is fired if old and new are equal and non-null.

   265      *

   266      * <p>

   267      * This is merely a convenience wrapper around the more general

   268      * firePropertyChange method that takes {@code

   269      * PropertyChangeEvent} value.

   270      *

   271      * @param propertyName  The programmatic name of the property

   272      *                      that was changed.

   273      * @param oldValue  The old value of the property.

   274      * @param newValue  The new value of the property.

   275      */

   276     protected final void firePropertyChange(String propertyName, Object oldValue, Object newValue) {

   277         pcs.firePropertyChange(propertyName, oldValue, newValue);

   278     }

   279 

   280     /**

   281      * Fire an existing PropertyChangeEvent to any registered listeners.

   282      * No event is fired if the given event's old and new values are

   283      * equal and non-null.

   284      * @param evt  The PropertyChangeEvent object.

   285      */

   286     protected final void firePropertyChange(PropertyChangeEvent evt) {

   287         pcs.firePropertyChange(evt);

   288     }

   289 

   290 

   291     /**

   292      * Report a bound indexed property update to any registered

   293      * listeners.

   294      * <p>

   295      * No event is fired if old and new values are equal

   296      * and non-null.

   297      *

   298      * <p>

   299      * This is merely a convenience wrapper around the more general

   300      * firePropertyChange method that takes {@code PropertyChangeEvent} value.

   301      *

   302      * @param propertyName The programmatic name of the property that

   303      *                     was changed.

   304      * @param index        index of the property element that was changed.

   305      * @param oldValue     The old value of the property.

   306      * @param newValue     The new value of the property.

   307      */

   308     protected final void fireIndexedPropertyChange(String propertyName,

   309             int index, Object oldValue, Object newValue) {

   310         pcs.fireIndexedPropertyChange(propertyName, index, oldValue, newValue);

   311     }

   312 

   313     /**

   314      * Check if there are any listeners for a specific property, including

   315      * those registered on all properties.  If <code>propertyName</code>

   316      * is null, only check for listeners registered on all properties.

   317      *

   318      * @param propertyName  the property name.

   319      * @return true if there are one or more listeners for the given property

   320      */

   321     protected final boolean hasPropertyChangeListeners(String propertyName) {

   322         return pcs.hasListeners(propertyName);

   323     }

   324 

   325     /**

   326      * Check if there are any listeners for a specific property, including

   327      * those registered on all properties.  If <code>propertyName</code>

   328      * is null, only check for listeners registered on all properties.

   329      *

   330      * @param propertyName  the property name.

   331      * @return true if there are one or more listeners for the given property

   332      */

   333     protected final boolean hasVetoableChangeListeners(String propertyName) {

   334         return vcs.hasListeners(propertyName);

   335     }

   336 

   337     /**

   338      * Add a VetoableListener to the listener list.

   339      * The listener is registered for all properties.

   340      * The same listener object may be added more than once, and will be called

   341      * as many times as it is added.

   342      * If <code>listener</code> is null, no exception is thrown and no action

   343      * is taken.

   344      *

   345      * @param listener  The VetoableChangeListener to be added

   346      */

   347 

   348     public final void addVetoableChangeListener(VetoableChangeListener listener) {

   349         vcs.addVetoableChangeListener(listener);

   350     }

   351 

   352     /**

   353      * Remove a VetoableChangeListener from the listener list.

   354      * This removes a VetoableChangeListener that was registered

   355      * for all properties.

   356      * If <code>listener</code> was added more than once to the same event

   357      * source, it will be notified one less time after being removed.

   358      * If <code>listener</code> is null, or was never added, no exception is

   359      * thrown and no action is taken.

   360      *

   361      * @param listener  The VetoableChangeListener to be removed

   362      */

   363     public final void removeVetoableChangeListener(VetoableChangeListener listener) {

   364         vcs.removeVetoableChangeListener(listener);

   365     }

   366 

   367     /**

   368      * Returns the list of VetoableChangeListeners. If named vetoable change listeners

   369      * were added, then VetoableChangeListenerProxy wrappers will returned

   370      * <p>

   371      * @return List of VetoableChangeListeners and VetoableChangeListenerProxys

   372      *         if named property change listeners were added.

   373      */

   374     public final VetoableChangeListener[] getVetoableChangeListeners(){

   375         return vcs.getVetoableChangeListeners();

   376     }

   377 

   378     /**

   379      * Add a VetoableChangeListener for a specific property.  The listener

   380      * will be invoked only when a call on fireVetoableChange names that

   381      * specific property.

   382      * The same listener object may be added more than once.  For each

   383      * property,  the listener will be invoked the number of times it was added

   384      * for that property.

   385      * If <code>propertyName</code> or <code>listener</code> is null, no

   386      * exception is thrown and no action is taken.

   387      *

   388      * @param propertyName  The name of the property to listen on.

   389      * @param listener  The VetoableChangeListener to be added

   390      */

   391 

   392     public final void addVetoableChangeListener(String propertyName,

   393                 VetoableChangeListener listener) {

   394         vcs.addVetoableChangeListener(propertyName, listener);

   395     }

   396 

   397     /**

   398      * Remove a VetoableChangeListener for a specific property.

   399      * If <code>listener</code> was added more than once to the same event

   400      * source for the specified property, it will be notified one less time

   401      * after being removed.

   402      * If <code>propertyName</code> is null, no exception is thrown and no

   403      * action is taken.

   404      * If <code>listener</code> is null, or was never added for the specified

   405      * property, no exception is thrown and no action is taken.

   406      *

   407      * @param propertyName  The name of the property that was listened on.

   408      * @param listener  The VetoableChangeListener to be removed

   409      */

   410 

   411     public final void removeVetoableChangeListener(String propertyName,

   412                 VetoableChangeListener listener) {

   413         vcs.removeVetoableChangeListener(propertyName, listener);

   414     }

   415 

   416     /**

   417      * Returns an array of all the listeners which have been associated

   418      * with the named property.

   419      *

   420      * @param propertyName  The name of the property being listened to

   421      * @return all the <code>VetoableChangeListeners</code> associated with

   422      *         the named property.  If no such listeners have been added,

   423      *         or if <code>propertyName</code> is null, an empty array is

   424      *         returned.

   425      */

   426     public final VetoableChangeListener[] getVetoableChangeListeners(String propertyName) {

   427         return vcs.getVetoableChangeListeners(propertyName);

   428     }

   429 

   430     /**

   431      * Report a vetoable property update to any registered listeners.  If

   432      * anyone vetos the change, then fire a new event reverting everyone to

   433      * the old value and then rethrow the PropertyVetoException.

   434      * <p>

   435      * No event is fired if old and new are equal and non-null.

   436      *

   437      * @param propertyName  The programmatic name of the property

   438      *                      that is about to change..

   439      * @param oldValue  The old value of the property.

   440      * @param newValue  The new value of the property.

   441      * @exception PropertyVetoException if the recipient wishes the property

   442      *              change to be rolled back.

   443      */

   444     protected final void fireVetoableChange(String propertyName,

   445                                             Object oldValue, Object newValue)

   446                                             throws PropertyVetoException {

   447          vcs.fireVetoableChange(propertyName, oldValue, newValue);

   448     }

   449 

   450     /**

   451      * Fire a vetoable property update to any registered listeners.  If

   452      * anyone vetos the change, then fire a new event reverting everyone to

   453      * the old value and then rethrow the PropertyVetoException.

   454      * <p>

   455      * No event is fired if old and new are equal and non-null.

   456      *

   457      * @param evt  The PropertyChangeEvent to be fired.

   458      * @exception PropertyVetoException if the recipient wishes the property

   459      *              change to be rolled back.

   460      */

   461     protected final void fireVetoableChange(PropertyChangeEvent evt)

   462                     throws PropertyVetoException {

   463         vcs.fireVetoableChange(evt);

   464     }

   465 

   466     /**

   467      * @inheritDoc

   468      */

   469     public Object clone() throws CloneNotSupportedException {

   470         AbstractBean result = (AbstractBean) super.clone();

   471         result.pcs = new PropertyChangeSupport(result);

   472         result.vcs = new VetoableChangeSupport(result);

   473         return result;

   474     }

   475 }