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