* Here is an example of {@code VetoableChangeSupport} usage that follows * the rules and recommendations laid out in the JavaBeans™ specification: *
{@code
* 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.
*
*
{@code
* 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