- * Here is an example of {@code VetoableChangeSupport} usage that follows - * the rules and recommendations laid out in the JavaBeans™ specification: - *
- * public class MyBean {
- * private final VetoableChangeSupport vcs = new VetoableChangeSupport(this);
- *
- * public void addVetoableChangeListener(VetoableChangeListener listener) {
- * this.vcs.addVetoableChangeListener(listener);
- * }
- *
- * public void removeVetoableChangeListener(VetoableChangeListener listener) {
- * this.vcs.removeVetoableChangeListener(listener);
- * }
- *
- * private String value;
- *
- * public String getValue() {
- * return this.value;
- * }
- *
- * public void setValue(String newValue) throws PropertyVetoException {
- * String oldValue = this.value;
- * this.vcs.fireVetoableChange("value", oldValue, newValue);
- * this.value = newValue;
- * }
- *
- * [...]
- * }
- *
- * - * A {@code VetoableChangeSupport} instance is thread-safe. - *
- * This class is serializable. When it is serialized it will save
- * (and restore) any listeners that are themselves serializable. Any
- * non-serializable listeners will be skipped during serialization.
- *
- * @see PropertyChangeSupport
- */
-public class VetoableChangeSupport implements Serializable {
- private VetoableChangeListenerMap map = new VetoableChangeListenerMap();
-
- /**
- * Constructs a VetoableChangeSupport object.
- *
- * @param sourceBean The bean to be given as the source for any events.
- */
- public VetoableChangeSupport(Object sourceBean) {
- if (sourceBean == null) {
- throw new NullPointerException();
- }
- source = sourceBean;
- }
-
- /**
- * Add a VetoableChangeListener 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 listener is null, no exception is thrown and no action
- * is taken.
- *
- * @param listener The VetoableChangeListener to be added
- */
- public void addVetoableChangeListener(VetoableChangeListener listener) {
- if (listener == null) {
- return;
- }
- if (listener instanceof VetoableChangeListenerProxy) {
- VetoableChangeListenerProxy proxy =
- (VetoableChangeListenerProxy)listener;
- // Call two argument add method.
- addVetoableChangeListener(proxy.getPropertyName(),
- proxy.getListener());
- } else {
- this.map.add(null, listener);
- }
- }
-
- /**
- * Remove a VetoableChangeListener from the listener list.
- * This removes a VetoableChangeListener that was registered
- * for all properties.
- * If listener was added more than once to the same event
- * source, it will be notified one less time after being removed.
- * If listener is null, or was never added, no exception is
- * thrown and no action is taken.
- *
- * @param listener The VetoableChangeListener to be removed
- */
- public void removeVetoableChangeListener(VetoableChangeListener listener) {
- if (listener == null) {
- return;
- }
- if (listener instanceof VetoableChangeListenerProxy) {
- VetoableChangeListenerProxy proxy =
- (VetoableChangeListenerProxy)listener;
- // Call two argument remove method.
- removeVetoableChangeListener(proxy.getPropertyName(),
- proxy.getListener());
- } else {
- this.map.remove(null, listener);
- }
- }
-
- /**
- * Returns an array of all the listeners that were added to the
- * VetoableChangeSupport object with addVetoableChangeListener().
- *
- * If some listeners have been added with a named property, then
- * the returned array will be a mixture of VetoableChangeListeners
- * and VetoableChangeListenerProxys. If the calling
- * method is interested in distinguishing the listeners then it must
- * test each element to see if it's a
- * VetoableChangeListenerProxy, perform the cast, and examine
- * the parameter.
- *
- *
- * VetoableChangeListener[] listeners = bean.getVetoableChangeListeners();
- * for (int i = 0; i < listeners.length; i++) {
- * if (listeners[i] instanceof VetoableChangeListenerProxy) {
- * VetoableChangeListenerProxy proxy =
- * (VetoableChangeListenerProxy)listeners[i];
- * if (proxy.getPropertyName().equals("foo")) {
- * // proxy is a VetoableChangeListener which was associated
- * // with the property named "foo"
- * }
- * }
- * }
- *
- *
- * @see VetoableChangeListenerProxy
- * @return all of the VetoableChangeListeners added or an
- * empty array if no listeners have been added
- * @since 1.4
- */
- public VetoableChangeListener[] getVetoableChangeListeners(){
- return this.map.getListeners();
- }
-
- /**
- * Add a VetoableChangeListener for a specific property. The listener
- * will be invoked only when a call on fireVetoableChange 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 propertyName or listener is null, no
- * exception is thrown and no action is taken.
- *
- * @param propertyName The name of the property to listen on.
- * @param listener The VetoableChangeListener to be added
- */
- public void addVetoableChangeListener(
- String propertyName,
- VetoableChangeListener listener) {
- if (listener == null || propertyName == null) {
- return;
- }
- listener = this.map.extract(listener);
- if (listener != null) {
- this.map.add(propertyName, listener);
- }
- }
-
- /**
- * Remove a VetoableChangeListener for a specific property.
- * If listener 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 propertyName is null, no exception is thrown and no
- * action is taken.
- * If listener 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 VetoableChangeListener to be removed
- */
- public void removeVetoableChangeListener(
- String propertyName,
- VetoableChangeListener listener) {
- if (listener == null || propertyName == null) {
- return;
- }
- listener = this.map.extract(listener);
- if (listener != null) {
- this.map.remove(propertyName, 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 the VetoableChangeListeners associated with
- * the named property. If no such listeners have been added,
- * or if propertyName is null, an empty array is
- * returned.
- * @since 1.4
- */
- public VetoableChangeListener[] getVetoableChangeListeners(String propertyName) {
- return this.map.getListeners(propertyName);
- }
-
- /**
- * Reports a constrained property update to listeners
- * that have been registered to track updates of
- * all properties or a property with the specified name.
- * - * Any listener can throw a {@code PropertyVetoException} to veto the update. - * If one of the listeners vetoes the update, this method passes - * a new "undo" {@code PropertyChangeEvent} that reverts to the old value - * to all listeners that already confirmed this update - * and throws the {@code PropertyVetoException} again. - *
- * No event is fired if old and new values are equal and non-null. - *
- * This is merely a convenience wrapper around the more general - * {@link #fireVetoableChange(PropertyChangeEvent)} method. - * - * @param propertyName the programmatic name of the property that is about to change - * @param oldValue the old value of the property - * @param newValue the new value of the property - * @throws PropertyVetoException if one of listeners vetoes the property update - */ - public void fireVetoableChange(String propertyName, Object oldValue, Object newValue) - throws PropertyVetoException { - if (oldValue == null || newValue == null || !oldValue.equals(newValue)) { - fireVetoableChange(new PropertyChangeEvent(this.source, propertyName, oldValue, newValue)); - } - } - - /** - * Reports an integer constrained property update to listeners - * that have been registered to track updates of - * all properties or a property with the specified name. - *
- * Any listener can throw a {@code PropertyVetoException} to veto the update. - * If one of the listeners vetoes the update, this method passes - * a new "undo" {@code PropertyChangeEvent} that reverts to the old value - * to all listeners that already confirmed this update - * and throws the {@code PropertyVetoException} again. - *
- * No event is fired if old and new values are equal. - *
- * This is merely a convenience wrapper around the more general - * {@link #fireVetoableChange(String, Object, Object)} method. - * - * @param propertyName the programmatic name of the property that is about to change - * @param oldValue the old value of the property - * @param newValue the new value of the property - * @throws PropertyVetoException if one of listeners vetoes the property update - */ - public void fireVetoableChange(String propertyName, int oldValue, int newValue) - throws PropertyVetoException { - if (oldValue != newValue) { - fireVetoableChange(propertyName, Integer.valueOf(oldValue), Integer.valueOf(newValue)); - } - } - - /** - * Reports a boolean constrained property update to listeners - * that have been registered to track updates of - * all properties or a property with the specified name. - *
- * Any listener can throw a {@code PropertyVetoException} to veto the update. - * If one of the listeners vetoes the update, this method passes - * a new "undo" {@code PropertyChangeEvent} that reverts to the old value - * to all listeners that already confirmed this update - * and throws the {@code PropertyVetoException} again. - *
- * No event is fired if old and new values are equal. - *
- * This is merely a convenience wrapper around the more general - * {@link #fireVetoableChange(String, Object, Object)} method. - * - * @param propertyName the programmatic name of the property that is about to change - * @param oldValue the old value of the property - * @param newValue the new value of the property - * @throws PropertyVetoException if one of listeners vetoes the property update - */ - public void fireVetoableChange(String propertyName, boolean oldValue, boolean newValue) - throws PropertyVetoException { - if (oldValue != newValue) { - fireVetoableChange(propertyName, Boolean.valueOf(oldValue), Boolean.valueOf(newValue)); - } - } - - /** - * Fires a property change event to listeners - * that have been registered to track updates of - * all properties or a property with the specified name. - *
- * Any listener can throw a {@code PropertyVetoException} to veto the update. - * If one of the listeners vetoes the update, this method passes - * a new "undo" {@code PropertyChangeEvent} that reverts to the old value - * to all listeners that already confirmed this update - * and throws the {@code PropertyVetoException} again. - *
- * No event is fired if the given event's old and new values are equal and non-null.
- *
- * @param event the {@code PropertyChangeEvent} to be fired
- * @throws PropertyVetoException if one of listeners vetoes the property update
- */
- public void fireVetoableChange(PropertyChangeEvent event)
- throws PropertyVetoException {
- Object oldValue = event.getOldValue();
- Object newValue = event.getNewValue();
- if (oldValue == null || newValue == null || !oldValue.equals(newValue)) {
- String name = event.getPropertyName();
-
- VetoableChangeListener[] common = this.map.get(null);
- VetoableChangeListener[] named = (name != null)
- ? this.map.get(name)
- : null;
-
- VetoableChangeListener[] listeners;
- if (common == null) {
- listeners = named;
- }
- else if (named == null) {
- listeners = common;
- }
- else {
- listeners = new VetoableChangeListener[common.length + named.length];
- System.arraycopy(common, 0, listeners, 0, common.length);
- System.arraycopy(named, 0, listeners, common.length, named.length);
- }
- if (listeners != null) {
- int current = 0;
- try {
- while (current < listeners.length) {
- listeners[current].vetoableChange(event);
- current++;
- }
- }
- catch (PropertyVetoException veto) {
- event = new PropertyChangeEvent(this.source, name, newValue, oldValue);
- for (int i = 0; i < current; i++) {
- try {
- listeners[i].vetoableChange(event);
- }
- catch (PropertyVetoException exception) {
- // ignore exceptions that occur during rolling back
- }
- }
- throw veto; // rethrow the veto exception
- }
- }
- }
- }
-
- /**
- * Check if there are any listeners for a specific property, including
- * those registered on all properties. If propertyName
- * 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) {
- return this.map.hasListeners(propertyName);
- }
-
- /**
- * @serialData Null terminated list of VetoableChangeListeners.
- *
- * At serialization time we skip non-serializable listeners and
- * only serialize the serializable listeners.
- */
- private void writeObject(ObjectOutputStream s) throws IOException {
- Hashtable