2 * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
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).
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.
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
27 import java.io.Serializable;
28 import java.io.ObjectStreamField;
29 import java.io.ObjectOutputStream;
30 import java.io.ObjectInputStream;
31 import java.io.IOException;
32 import java.util.Hashtable;
33 import java.util.Map.Entry;
34 import org.apidesign.bck2brwsr.emul.lang.System;
37 * This is a utility class that can be used by beans that support constrained
38 * properties. It manages a list of listeners and dispatches
39 * {@link PropertyChangeEvent}s to them. You can use an instance of this class
40 * as a member field of your bean and delegate these types of work to it.
41 * The {@link VetoableChangeListener} can be registered for all properties
42 * or for a property specified by name.
44 * Here is an example of {@code VetoableChangeSupport} usage that follows
45 * the rules and recommendations laid out in the JavaBeans™ specification:
47 * public class MyBean {
48 * private final VetoableChangeSupport vcs = new VetoableChangeSupport(this);
50 * public void addVetoableChangeListener(VetoableChangeListener listener) {
51 * this.vcs.addVetoableChangeListener(listener);
54 * public void removeVetoableChangeListener(VetoableChangeListener listener) {
55 * this.vcs.removeVetoableChangeListener(listener);
58 * private String value;
60 * public String getValue() {
64 * public void setValue(String newValue) throws PropertyVetoException {
65 * String oldValue = this.value;
66 * this.vcs.fireVetoableChange("value", oldValue, newValue);
67 * this.value = newValue;
74 * A {@code VetoableChangeSupport} instance is thread-safe.
76 * This class is serializable. When it is serialized it will save
77 * (and restore) any listeners that are themselves serializable. Any
78 * non-serializable listeners will be skipped during serialization.
80 * @see PropertyChangeSupport
82 public class VetoableChangeSupport implements Serializable {
83 private VetoableChangeListenerMap map = new VetoableChangeListenerMap();
86 * Constructs a <code>VetoableChangeSupport</code> object.
88 * @param sourceBean The bean to be given as the source for any events.
90 public VetoableChangeSupport(Object sourceBean) {
91 if (sourceBean == null) {
92 throw new NullPointerException();
98 * Add a VetoableChangeListener to the listener list.
99 * The listener is registered for all properties.
100 * The same listener object may be added more than once, and will be called
101 * as many times as it is added.
102 * If <code>listener</code> is null, no exception is thrown and no action
105 * @param listener The VetoableChangeListener to be added
107 public void addVetoableChangeListener(VetoableChangeListener listener) {
108 if (listener == null) {
111 if (listener instanceof VetoableChangeListenerProxy) {
112 VetoableChangeListenerProxy proxy =
113 (VetoableChangeListenerProxy)listener;
114 // Call two argument add method.
115 addVetoableChangeListener(proxy.getPropertyName(),
116 proxy.getListener());
118 this.map.add(null, listener);
123 * Remove a VetoableChangeListener from the listener list.
124 * This removes a VetoableChangeListener that was registered
125 * for all properties.
126 * If <code>listener</code> was added more than once to the same event
127 * source, it will be notified one less time after being removed.
128 * If <code>listener</code> is null, or was never added, no exception is
129 * thrown and no action is taken.
131 * @param listener The VetoableChangeListener to be removed
133 public void removeVetoableChangeListener(VetoableChangeListener listener) {
134 if (listener == null) {
137 if (listener instanceof VetoableChangeListenerProxy) {
138 VetoableChangeListenerProxy proxy =
139 (VetoableChangeListenerProxy)listener;
140 // Call two argument remove method.
141 removeVetoableChangeListener(proxy.getPropertyName(),
142 proxy.getListener());
144 this.map.remove(null, listener);
149 * Returns an array of all the listeners that were added to the
150 * VetoableChangeSupport object with addVetoableChangeListener().
152 * If some listeners have been added with a named property, then
153 * the returned array will be a mixture of VetoableChangeListeners
154 * and <code>VetoableChangeListenerProxy</code>s. If the calling
155 * method is interested in distinguishing the listeners then it must
156 * test each element to see if it's a
157 * <code>VetoableChangeListenerProxy</code>, perform the cast, and examine
161 * VetoableChangeListener[] listeners = bean.getVetoableChangeListeners();
162 * for (int i = 0; i < listeners.length; i++) {
163 * if (listeners[i] instanceof VetoableChangeListenerProxy) {
164 * VetoableChangeListenerProxy proxy =
165 * (VetoableChangeListenerProxy)listeners[i];
166 * if (proxy.getPropertyName().equals("foo")) {
167 * // proxy is a VetoableChangeListener which was associated
168 * // with the property named "foo"
174 * @see VetoableChangeListenerProxy
175 * @return all of the <code>VetoableChangeListeners</code> added or an
176 * empty array if no listeners have been added
179 public VetoableChangeListener[] getVetoableChangeListeners(){
180 return this.map.getListeners();
184 * Add a VetoableChangeListener for a specific property. The listener
185 * will be invoked only when a call on fireVetoableChange names that
187 * The same listener object may be added more than once. For each
188 * property, the listener will be invoked the number of times it was added
190 * If <code>propertyName</code> or <code>listener</code> is null, no
191 * exception is thrown and no action is taken.
193 * @param propertyName The name of the property to listen on.
194 * @param listener The VetoableChangeListener to be added
196 public void addVetoableChangeListener(
198 VetoableChangeListener listener) {
199 if (listener == null || propertyName == null) {
202 listener = this.map.extract(listener);
203 if (listener != null) {
204 this.map.add(propertyName, listener);
209 * Remove a VetoableChangeListener for a specific property.
210 * If <code>listener</code> was added more than once to the same event
211 * source for the specified property, it will be notified one less time
212 * after being removed.
213 * If <code>propertyName</code> is null, no exception is thrown and no
215 * If <code>listener</code> is null, or was never added for the specified
216 * property, no exception is thrown and no action is taken.
218 * @param propertyName The name of the property that was listened on.
219 * @param listener The VetoableChangeListener to be removed
221 public void removeVetoableChangeListener(
223 VetoableChangeListener listener) {
224 if (listener == null || propertyName == null) {
227 listener = this.map.extract(listener);
228 if (listener != null) {
229 this.map.remove(propertyName, listener);
234 * Returns an array of all the listeners which have been associated
235 * with the named property.
237 * @param propertyName The name of the property being listened to
238 * @return all the <code>VetoableChangeListeners</code> associated with
239 * the named property. If no such listeners have been added,
240 * or if <code>propertyName</code> is null, an empty array is
244 public VetoableChangeListener[] getVetoableChangeListeners(String propertyName) {
245 return this.map.getListeners(propertyName);
249 * Reports a constrained property update to listeners
250 * that have been registered to track updates of
251 * all properties or a property with the specified name.
253 * Any listener can throw a {@code PropertyVetoException} to veto the update.
254 * If one of the listeners vetoes the update, this method passes
255 * a new "undo" {@code PropertyChangeEvent} that reverts to the old value
256 * to all listeners that already confirmed this update
257 * and throws the {@code PropertyVetoException} again.
259 * No event is fired if old and new values are equal and non-null.
261 * This is merely a convenience wrapper around the more general
262 * {@link #fireVetoableChange(PropertyChangeEvent)} method.
264 * @param propertyName the programmatic name of the property that is about to change
265 * @param oldValue the old value of the property
266 * @param newValue the new value of the property
267 * @throws PropertyVetoException if one of listeners vetoes the property update
269 public void fireVetoableChange(String propertyName, Object oldValue, Object newValue)
270 throws PropertyVetoException {
271 if (oldValue == null || newValue == null || !oldValue.equals(newValue)) {
272 fireVetoableChange(new PropertyChangeEvent(this.source, propertyName, oldValue, newValue));
277 * Reports an integer constrained property update to listeners
278 * that have been registered to track updates of
279 * all properties or a property with the specified name.
281 * Any listener can throw a {@code PropertyVetoException} to veto the update.
282 * If one of the listeners vetoes the update, this method passes
283 * a new "undo" {@code PropertyChangeEvent} that reverts to the old value
284 * to all listeners that already confirmed this update
285 * and throws the {@code PropertyVetoException} again.
287 * No event is fired if old and new values are equal.
289 * This is merely a convenience wrapper around the more general
290 * {@link #fireVetoableChange(String, Object, Object)} method.
292 * @param propertyName the programmatic name of the property that is about to change
293 * @param oldValue the old value of the property
294 * @param newValue the new value of the property
295 * @throws PropertyVetoException if one of listeners vetoes the property update
297 public void fireVetoableChange(String propertyName, int oldValue, int newValue)
298 throws PropertyVetoException {
299 if (oldValue != newValue) {
300 fireVetoableChange(propertyName, Integer.valueOf(oldValue), Integer.valueOf(newValue));
305 * Reports a boolean constrained property update to listeners
306 * that have been registered to track updates of
307 * all properties or a property with the specified name.
309 * Any listener can throw a {@code PropertyVetoException} to veto the update.
310 * If one of the listeners vetoes the update, this method passes
311 * a new "undo" {@code PropertyChangeEvent} that reverts to the old value
312 * to all listeners that already confirmed this update
313 * and throws the {@code PropertyVetoException} again.
315 * No event is fired if old and new values are equal.
317 * This is merely a convenience wrapper around the more general
318 * {@link #fireVetoableChange(String, Object, Object)} method.
320 * @param propertyName the programmatic name of the property that is about to change
321 * @param oldValue the old value of the property
322 * @param newValue the new value of the property
323 * @throws PropertyVetoException if one of listeners vetoes the property update
325 public void fireVetoableChange(String propertyName, boolean oldValue, boolean newValue)
326 throws PropertyVetoException {
327 if (oldValue != newValue) {
328 fireVetoableChange(propertyName, Boolean.valueOf(oldValue), Boolean.valueOf(newValue));
333 * Fires a property change event to listeners
334 * that have been registered to track updates of
335 * all properties or a property with the specified name.
337 * Any listener can throw a {@code PropertyVetoException} to veto the update.
338 * If one of the listeners vetoes the update, this method passes
339 * a new "undo" {@code PropertyChangeEvent} that reverts to the old value
340 * to all listeners that already confirmed this update
341 * and throws the {@code PropertyVetoException} again.
343 * No event is fired if the given event's old and new values are equal and non-null.
345 * @param event the {@code PropertyChangeEvent} to be fired
346 * @throws PropertyVetoException if one of listeners vetoes the property update
348 public void fireVetoableChange(PropertyChangeEvent event)
349 throws PropertyVetoException {
350 Object oldValue = event.getOldValue();
351 Object newValue = event.getNewValue();
352 if (oldValue == null || newValue == null || !oldValue.equals(newValue)) {
353 String name = event.getPropertyName();
355 VetoableChangeListener[] common = this.map.get(null);
356 VetoableChangeListener[] named = (name != null)
360 VetoableChangeListener[] listeners;
361 if (common == null) {
364 else if (named == null) {
368 listeners = new VetoableChangeListener[common.length + named.length];
369 System.arraycopy(common, 0, listeners, 0, common.length);
370 System.arraycopy(named, 0, listeners, common.length, named.length);
372 if (listeners != null) {
375 while (current < listeners.length) {
376 listeners[current].vetoableChange(event);
380 catch (PropertyVetoException veto) {
381 event = new PropertyChangeEvent(this.source, name, newValue, oldValue);
382 for (int i = 0; i < current; i++) {
384 listeners[i].vetoableChange(event);
386 catch (PropertyVetoException exception) {
387 // ignore exceptions that occur during rolling back
390 throw veto; // rethrow the veto exception
397 * Check if there are any listeners for a specific property, including
398 * those registered on all properties. If <code>propertyName</code>
399 * is null, only check for listeners registered on all properties.
401 * @param propertyName the property name.
402 * @return true if there are one or more listeners for the given property
404 public boolean hasListeners(String propertyName) {
405 return this.map.hasListeners(propertyName);
409 * @serialData Null terminated list of <code>VetoableChangeListeners</code>.
411 * At serialization time we skip non-serializable listeners and
412 * only serialize the serializable listeners.
414 private void writeObject(ObjectOutputStream s) throws IOException {
415 Hashtable<String, VetoableChangeSupport> children = null;
416 VetoableChangeListener[] listeners = null;
417 synchronized (this.map) {
418 for (Entry<String, VetoableChangeListener[]> entry : this.map.getEntries()) {
419 String property = entry.getKey();
420 if (property == null) {
421 listeners = entry.getValue();
423 if (children == null) {
424 children = new Hashtable<String, VetoableChangeSupport>();
426 VetoableChangeSupport vcs = new VetoableChangeSupport(this.source);
427 vcs.map.set(null, entry.getValue());
428 children.put(property, vcs);
432 ObjectOutputStream.PutField fields = s.putFields();
433 fields.put("children", children);
434 fields.put("source", this.source);
435 fields.put("vetoableChangeSupportSerializedDataVersion", 2);
438 if (listeners != null) {
439 for (VetoableChangeListener l : listeners) {
440 if (l instanceof Serializable) {
448 private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException {
449 this.map = new VetoableChangeListenerMap();
451 ObjectInputStream.GetField fields = s.readFields();
453 Hashtable<String, VetoableChangeSupport> children = (Hashtable<String, VetoableChangeSupport>) fields.get("children", null);
454 this.source = fields.get("source", null);
455 fields.get("vetoableChangeSupportSerializedDataVersion", 2);
457 Object listenerOrNull;
458 while (null != (listenerOrNull = s.readObject())) {
459 this.map.add(null, (VetoableChangeListener)listenerOrNull);
461 if (children != null) {
462 for (Entry<String, VetoableChangeSupport> entry : children.entrySet()) {
463 for (VetoableChangeListener listener : entry.getValue().getVetoableChangeListeners()) {
464 this.map.add(entry.getKey(), listener);
471 * The object to be provided as the "source" for any generated events.
473 private Object source;
476 * @serialField children Hashtable
477 * @serialField source Object
478 * @serialField vetoableChangeSupportSerializedDataVersion int
480 private static final ObjectStreamField[] serialPersistentFields = {
481 new ObjectStreamField("children", Hashtable.class),
482 new ObjectStreamField("source", Object.class),
483 new ObjectStreamField("vetoableChangeSupportSerializedDataVersion", Integer.TYPE)
487 * Serialization version ID, so we're compatible with JDK 1.1
489 static final long serialVersionUID = -5090210921595982017L;
492 * This is a {@link ChangeListenerMap ChangeListenerMap} implementation
493 * that works with {@link VetoableChangeListener VetoableChangeListener} objects.
495 private static final class VetoableChangeListenerMap extends ChangeListenerMap<VetoableChangeListener> {
496 private static final VetoableChangeListener[] EMPTY = {};
499 * Creates an array of {@link VetoableChangeListener VetoableChangeListener} objects.
500 * This method uses the same instance of the empty array
501 * when {@code length} equals {@code 0}.
503 * @param length the array length
504 * @return an array with specified length
507 protected VetoableChangeListener[] newArray(int length) {
509 ? new VetoableChangeListener[length]
514 * Creates a {@link VetoableChangeListenerProxy VetoableChangeListenerProxy}
515 * object for the specified property.
517 * @param name the name of the property to listen on
518 * @param listener the listener to process events
519 * @return a {@code VetoableChangeListenerProxy} object
522 protected VetoableChangeListener newProxy(String name, VetoableChangeListener listener) {
523 return new VetoableChangeListenerProxy(name, listener);