001    /* VetoableChangeSupport.java -- support to manage vetoable change listeners
002       Copyright (C) 1998, 1999, 2000, 2002, 2005, 2006,
003       Free Software Foundation, Inc.
004    
005    This file is part of GNU Classpath.
006    
007    GNU Classpath is free software; you can redistribute it and/or modify
008    it under the terms of the GNU General Public License as published by
009    the Free Software Foundation; either version 2, or (at your option)
010    any later version.
011    
012    GNU Classpath is distributed in the hope that it will be useful, but
013    WITHOUT ANY WARRANTY; without even the implied warranty of
014    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015    General Public License for more details.
016    
017    You should have received a copy of the GNU General Public License
018    along with GNU Classpath; see the file COPYING.  If not, write to the
019    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
020    02110-1301 USA.
021    
022    Linking this library statically or dynamically with other modules is
023    making a combined work based on this library.  Thus, the terms and
024    conditions of the GNU General Public License cover the whole
025    combination.
026    
027    As a special exception, the copyright holders of this library give you
028    permission to link this library with independent modules to produce an
029    executable, regardless of the license terms of these independent
030    modules, and to copy and distribute the resulting executable under
031    terms of your choice, provided that you also meet, for each linked
032    independent module, the terms and conditions of the license of that
033    module.  An independent module is a module which is not derived from
034    or based on this library.  If you modify this library, you may extend
035    this exception to your version of the library, but you are not
036    obligated to do so.  If you do not wish to do so, delete this
037    exception statement from your version. */
038    
039    
040    package java.beans;
041    
042    import java.io.IOException;
043    import java.io.ObjectInputStream;
044    import java.io.ObjectOutputStream;
045    import java.io.Serializable;
046    import java.util.ArrayList;
047    import java.util.Arrays;
048    import java.util.Hashtable;
049    import java.util.Iterator;
050    import java.util.Map.Entry;
051    import java.util.Vector;
052    
053    /**
054     * VetoableChangeSupport makes it easy to fire vetoable change events and
055     * handle listeners. It allows chaining of listeners, as well as filtering
056     * by property name. In addition, it will serialize only those listeners
057     * which are serializable, ignoring the others without problem. This class
058     * is thread-safe.
059     *
060     * @author John Keiser
061     * @author Eric Blake (ebb9@email.byu.edu)
062     * @since 1.1
063     * @status updated to 1.4
064     */
065    public class VetoableChangeSupport implements Serializable
066    {
067      /**
068       * Compatible with JDK 1.1+.
069       */
070      private static final long serialVersionUID = -5090210921595982017L;
071    
072      /**
073       * Maps property names (String) to named listeners (VetoableChangeSupport).
074       * If this is a child instance, this field will be null.
075       *
076       * @serial the map of property names to named listener managers
077       * @since 1.2
078       */
079      private Hashtable children;
080    
081      /**
082       * The non-null source object for any generated events.
083       *
084       * @serial the event source
085       */
086      private final Object source;
087    
088      /**
089       * A field to compare serialization versions - this class uses version 2.
090       *
091       * @serial the serialization format
092       */
093      private static final int vetoableChangeSupportSerializedDataVersion = 2;
094    
095      /**
096       * The list of all registered vetoable listeners. If this instance was
097       * created by user code, this only holds the global listeners (ie. not tied
098       * to a name), and may be null. If it was created by this class, as a
099       * helper for named properties, then this vector will be non-null, and this
100       * instance appears as a value in the <code>children</code> hashtable of
101       * another instance, so that the listeners are tied to the key of that
102       * hashtable entry.
103       */
104      private transient Vector listeners;
105    
106      /**
107       * Create a VetoableChangeSupport to work with a specific source bean.
108       *
109       * @param source the source bean to use
110       * @throws NullPointerException if source is null
111       */
112      public VetoableChangeSupport(Object source)
113      {
114        this.source = source;
115        if (source == null)
116          throw new NullPointerException();
117      }
118    
119      /**
120       * Adds a VetoableChangeListener to the list of global listeners. All
121       * vetoable change events will be sent to this listener. The listener add
122       * is not unique: that is, <em>n</em> adds with the same listener will
123       * result in <em>n</em> events being sent to that listener for every
124       * vetoable change. This method will unwrap a VetoableChangeListenerProxy,
125       * registering the underlying delegate to the named property list.
126       *
127       * @param l the listener to add (<code>null</code> ignored).
128       */
129      public synchronized void addVetoableChangeListener(VetoableChangeListener l)
130      {
131        if (l == null)
132          return;
133        if (l instanceof VetoableChangeListenerProxy)
134          {
135            VetoableChangeListenerProxy p = (VetoableChangeListenerProxy) l;
136            addVetoableChangeListener(p.propertyName,
137                                      (VetoableChangeListener) p.getListener());
138          }
139        else
140          {
141            if (listeners == null)
142              listeners = new Vector();
143            listeners.add(l);
144          }
145      }
146    
147      /**
148       * Removes a VetoableChangeListener from the list of global listeners. If
149       * any specific properties are being listened on, they must be deregistered
150       * by themselves; this will only remove the general listener to all
151       * properties. If <code>add()</code> has been called multiple times for a
152       * particular listener, <code>remove()</code> will have to be called the
153       * same number of times to deregister it. This method will unwrap a
154       * VetoableChangeListenerProxy, removing the underlying delegate from the
155       * named property list.
156       *
157       * @param l the listener to remove
158       */
159      public synchronized void
160        removeVetoableChangeListener(VetoableChangeListener l)
161      {
162        if (l instanceof VetoableChangeListenerProxy)
163          {
164            VetoableChangeListenerProxy p = (VetoableChangeListenerProxy) l;
165            removeVetoableChangeListener(p.propertyName,
166                                         (VetoableChangeListener) p.getListener());
167          }
168        else if (listeners != null)
169          {
170            listeners.remove(l);
171            if (listeners.isEmpty())
172              listeners = null;
173          }
174      }
175    
176      /**
177       * Returns an array of all registered vetoable change listeners. Those that
178       * were registered under a name will be wrapped in a
179       * <code>VetoableChangeListenerProxy</code>, so you must check whether the
180       * listener is an instance of the proxy class in order to see what name the
181       * real listener is registered under. If there are no registered listeners,
182       * this returns an empty array.
183       *
184       * @return the array of registered listeners
185       * @see VetoableChangeListenerProxy
186       * @since 1.4
187       */
188      public synchronized VetoableChangeListener[] getVetoableChangeListeners()
189      {
190        ArrayList list = new ArrayList();
191        if (listeners != null)
192          list.addAll(listeners);
193        if (children != null)
194          {
195            int i = children.size();
196            Iterator iter = children.entrySet().iterator();
197            while (--i >= 0)
198              {
199                Entry e = (Entry) iter.next();
200                String name = (String) e.getKey();
201                Vector v = ((VetoableChangeSupport) e.getValue()).listeners;
202                int j = v.size();
203                while (--j >= 0)
204                  list.add(new VetoableChangeListenerProxy
205                    (name, (VetoableChangeListener) v.get(j)));
206              }
207          }
208        return (VetoableChangeListener[])
209          list.toArray(new VetoableChangeListener[list.size()]);
210      }
211    
212      /**
213       * Adds a VetoableChangeListener listening on the specified property. Events
214       * will be sent to the listener only if the property name matches. The
215       * listener add is not unique; that is, <em>n</em> adds on a particular
216       * property for a particular listener will result in <em>n</em> events
217       * being sent to that listener when that property is changed. The effect is
218       * cumulative, too; if you are registered to listen to receive events on
219       * all vetoable changes, and then you register on a particular property,
220       * you will receive change events for that property twice. This method
221       * will unwrap a VetoableChangeListenerProxy, registering the underlying
222       * delegate to the named property list if the names match, and discarding
223       * it otherwise.
224       *
225       * @param propertyName the name of the property to listen on
226       * @param l the listener to add
227       */
228      public synchronized void addVetoableChangeListener(String propertyName,
229                                                         VetoableChangeListener l)
230      {
231        if (propertyName == null || l == null)
232          return;
233        while (l instanceof VetoableChangeListenerProxy)
234          {
235            VetoableChangeListenerProxy p = (VetoableChangeListenerProxy) l;
236            if (propertyName == null ? p.propertyName != null
237                : ! propertyName.equals(p.propertyName))
238              return;
239            l = (VetoableChangeListener) p.getListener();
240          }
241        VetoableChangeSupport s = null;
242        if (children == null)
243          children = new Hashtable();
244        else
245          s = (VetoableChangeSupport) children.get(propertyName);
246        if (s == null)
247          {
248            s = new VetoableChangeSupport(source);
249            s.listeners = new Vector();
250            children.put(propertyName, s);
251          }
252        s.listeners.add(l);
253      }
254    
255      /**
256       * Removes a VetoableChangeListener from listening to a specific property.
257       * If <code>add()</code> has been called multiple times for a particular
258       * listener on a property, <code>remove()</code> will have to be called the
259       * same number of times to deregister it. This method will unwrap a
260       * VetoableChangeListenerProxy, removing the underlying delegate from the
261       * named property list if the names match.
262       *
263       * @param propertyName the property to stop listening on
264       * @param l the listener to remove
265       * @throws NullPointerException if propertyName is null
266       */
267      public synchronized void
268        removeVetoableChangeListener(String propertyName, VetoableChangeListener l)
269      {
270        if (children == null)
271          return;
272        VetoableChangeSupport s
273          = (VetoableChangeSupport) children.get(propertyName);
274        if (s == null)
275          return;
276        while (l instanceof VetoableChangeListenerProxy)
277          {
278            VetoableChangeListenerProxy p = (VetoableChangeListenerProxy) l;
279            if (propertyName == null ? p.propertyName != null
280                : ! propertyName.equals(p.propertyName))
281              return;
282            l = (VetoableChangeListener) p.getListener();
283          }
284        s.listeners.remove(l);
285        if (s.listeners.isEmpty())
286          {
287            children.remove(propertyName);
288            if (children.isEmpty())
289              children = null;
290          }
291      }
292    
293      /**
294       * Returns an array of all vetoable change listeners registered under the
295       * given property name. If there are no registered listeners, this returns
296       * an empty array.
297       *
298       * @return the array of registered listeners
299       * @throws NullPointerException if propertyName is null
300       * @since 1.4
301       */
302      public synchronized VetoableChangeListener[]
303        getVetoableChangeListeners(String propertyName)
304      {
305        if (children == null)
306          return new VetoableChangeListener[0];
307        VetoableChangeSupport s
308          = (VetoableChangeSupport) children.get(propertyName);
309        if (s == null)
310          return new VetoableChangeListener[0];
311        return (VetoableChangeListener[])
312          s.listeners.toArray(new VetoableChangeListener[s.listeners.size()]);
313      }
314    
315      /**
316       * Fire a PropertyChangeEvent containing the old and new values of the
317       * property to all the global listeners, and to all the listeners for the
318       * specified property name. This does nothing if old and new are non-null
319       * and equal. If the change is vetoed, a new event is fired to notify
320       * listeners about the rollback before the exception is thrown.
321       *
322       * @param propertyName the name of the property that changed
323       * @param oldVal the old value
324       * @param newVal the new value
325       * @throws PropertyVetoException if the change is vetoed by a listener
326       */
327      public void fireVetoableChange(String propertyName,
328                                     Object oldVal, Object newVal)
329        throws PropertyVetoException
330      {
331        fireVetoableChange(new PropertyChangeEvent(source, propertyName,
332                                                   oldVal, newVal));
333      }
334    
335      /**
336       * Fire a PropertyChangeEvent containing the old and new values of the
337       * property to all the global listeners, and to all the listeners for the
338       * specified property name. This does nothing if old and new are equal.
339       * If the change is vetoed, a new event is fired to notify listeners about
340       * the rollback before the exception is thrown.
341       *
342       * @param propertyName the name of the property that changed
343       * @param oldVal the old value
344       * @param newVal the new value
345       * @throws PropertyVetoException if the change is vetoed by a listener
346       */
347      public void fireVetoableChange(String propertyName, int oldVal, int newVal)
348        throws PropertyVetoException
349      {
350        if (oldVal != newVal)
351          fireVetoableChange(new PropertyChangeEvent(source, propertyName,
352                                                     Integer.valueOf(oldVal),
353                                                     Integer.valueOf(newVal)));
354      }
355    
356      /**
357       * Fire a PropertyChangeEvent containing the old and new values of the
358       * property to all the global listeners, and to all the listeners for the
359       * specified property name. This does nothing if old and new are equal.
360       * If the change is vetoed, a new event is fired to notify listeners about
361       * the rollback before the exception is thrown.
362       *
363       * @param propertyName the name of the property that changed
364       * @param oldVal the old value
365       * @param newVal the new value
366       * @throws PropertyVetoException if the change is vetoed by a listener
367       */
368      public void fireVetoableChange(String propertyName,
369                                     boolean oldVal, boolean newVal)
370        throws PropertyVetoException
371      {
372        if (oldVal != newVal)
373          fireVetoableChange(new PropertyChangeEvent(source, propertyName,
374                                                     Boolean.valueOf(oldVal),
375                                                     Boolean.valueOf(newVal)));
376      }
377    
378      /**
379       * Fire a PropertyChangeEvent to all the global listeners, and to all the
380       * listeners for the specified property name. This does nothing if old and
381       * new values of the event are equal. If the change is vetoed, a new event
382       * is fired to notify listeners about the rollback before the exception is
383       * thrown.
384       *
385       * @param event the event to fire
386       * @throws NullPointerException if event is null
387       * @throws PropertyVetoException if the change is vetoed by a listener
388       */
389      public void fireVetoableChange(PropertyChangeEvent event)
390        throws PropertyVetoException
391      {
392        if (event.oldValue != null && event.oldValue.equals(event.newValue))
393          return;
394        Vector v = listeners; // Be thread-safe.
395        if (v != null)
396          {
397            int i = v.size();
398            try
399              {
400                while (--i >= 0)
401                  ((VetoableChangeListener) v.get(i)).vetoableChange(event);
402              }
403            catch (PropertyVetoException e)
404              {
405                event = event.rollback();
406                int limit = i;
407                i = v.size();
408                while (--i >= limit)
409                  ((VetoableChangeListener) v.get(i)).vetoableChange(event);
410                throw e;
411              }
412          }
413        Hashtable h = children; // Be thread-safe.
414        if (h != null && event.propertyName != null)
415          {
416            VetoableChangeSupport s
417              = (VetoableChangeSupport) h.get(event.propertyName);
418            if (s != null)
419              {
420                Vector v1 = s.listeners; // Be thread-safe.
421                int i = v1 == null ? 0 : v1.size();
422                try
423                  {
424                    while (--i >= 0)
425                      ((VetoableChangeListener) v1.get(i)).vetoableChange(event);
426                  }
427                catch (PropertyVetoException e)
428                  {
429                    event = event.rollback();
430                    int limit = i;
431                    i = v.size();
432                    while (--i >= 0)
433                      ((VetoableChangeListener) v.get(i)).vetoableChange(event);
434                    i = v1.size();
435                    while (--i >= limit)
436                      ((VetoableChangeListener) v1.get(i)).vetoableChange(event);
437                    throw e;
438                  }
439              }
440          }
441      }
442    
443      /**
444       * Tell whether the specified property is being listened on or not. This
445       * will only return <code>true</code> if there are listeners on all
446       * properties or if there is a listener specifically on this property.
447       *
448       * @param propertyName the property that may be listened on
449       * @return whether the property is being listened on
450       * @throws NullPointerException if propertyName is null
451       */
452      public synchronized boolean hasListeners(String propertyName)
453      {
454        return listeners != null || (children != null
455                                     && children.get(propertyName) != null);
456      }
457    
458      /**
459       * Saves the state of the object to the stream.
460       *
461       * @param s the stream to write to
462       * @throws IOException if anything goes wrong
463       * @serialData this writes out a null-terminated list of serializable
464       *             global vetoable change listeners (the listeners for a named
465       *             property are written out as the global listeners of the
466       *             children, when the children hashtable is saved)
467       */
468      private synchronized void writeObject(ObjectOutputStream s)
469        throws IOException
470      {
471        s.defaultWriteObject();
472        if (listeners != null)
473          {
474            int i = listeners.size();
475            while (--i >= 0)
476              if (listeners.get(i) instanceof Serializable)
477                s.writeObject(listeners.get(i));
478          }
479        s.writeObject(null);
480      }
481    
482      /**
483       * Reads the object back from stream (deserialization).
484       *
485       * XXX Since serialization for 1.1 streams was not documented, this may
486       * not work if vetoableChangeSupportSerializedDataVersion is 1.
487       *
488       * @param s the stream to read from
489       * @throws IOException if reading the stream fails
490       * @throws ClassNotFoundException if deserialization fails
491       * @serialData this reads in a null-terminated list of serializable
492       *             global vetoable change listeners (the listeners for a named
493       *             property are written out as the global listeners of the
494       *             children, when the children hashtable is saved)
495       */
496      private void readObject(ObjectInputStream s)
497        throws IOException, ClassNotFoundException
498      {
499        s.defaultReadObject();
500        VetoableChangeListener l = (VetoableChangeListener) s.readObject();
501        while (l != null)
502          {
503            addVetoableChangeListener(l);
504            l = (VetoableChangeListener) s.readObject();
505          }
506        // Sun is not as careful with children as we are, and lets some proxys
507        // in that can never receive events. So, we clean up anything that got
508        // serialized, to make sure our invariants hold.
509        if (children != null)
510          {
511            int i = children.size();
512            Iterator iter = children.entrySet().iterator();
513            while (--i >= 0)
514              {
515                Entry e = (Entry) iter.next();
516                String name = (String) e.getKey();
517                VetoableChangeSupport vcs = (VetoableChangeSupport) e.getValue();
518                if (vcs.listeners == null)
519                  vcs.listeners = new Vector();
520                if (vcs.children != null)
521                  vcs.listeners.addAll
522                    (Arrays.asList(vcs.getVetoableChangeListeners(name)));
523                if (vcs.listeners.size() == 0)
524                  iter.remove();
525                else
526                  vcs.children = null;
527              }
528            if (children.size() == 0)
529              children = null;
530          }
531      }
532    } // class VetoableChangeSupport