Top Description Inners Fields Constructors Methods
java.beans

public Class VetoableChangeSupport

extends Object
implements Serializable
Class Inheritance
All Implemented Interfaces
java.io.Serializable
Imports
java.io.IOException, .ObjectInputStream, .ObjectOutputStream, .ObjectStreamField, .Serial, .Serializable, java.util.Hashtable, .Map.Entry
This is a utility class that can be used by beans that support constrained properties. It manages a list of listeners and dispatches PropertyChangeEvents to them. You can use an instance of this class as a member field of your bean and delegate these types of work to it. The VetoableChangeListener can be registered for all properties or for a property specified by name.

Here is an example of 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 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.

Since
1.1
See Also
PropertyChangeSupport

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
VetoableChangeSupport.VetoableChangeListenerMap

This is a ChangeListenerMap implementation that works with VetoableChangeListener objects.

Field Summary

Modifier and TypeField and Description
private VetoableChangeSupport.VetoableChangeListenerMap
map

private static final ObjectStreamField[]
serialPersistentFields

private static final long
serialVersionUID

Use serialVersionUID from JDK 1.1 for interoperability.

private Object
source

The object to be provided as the "source" for any generated events.

Constructor Summary

AccessConstructor and Description
public
VetoableChangeSupport(Object
The bean to be given as the source for any events.
sourceBean)

Constructs a VetoableChangeSupport object.

Method Summary

Modifier and TypeMethod and Description
public void
addVetoableChangeListener(VetoableChangeListener
The VetoableChangeListener to be added
listener)

Add a VetoableChangeListener to the listener list.

public void
addVetoableChangeListener(String
The name of the property to listen on.
propertyName, VetoableChangeListener
The VetoableChangeListener to be added
listener)

Add a VetoableChangeListener for a specific property.

public void
fireVetoableChange(String
the programmatic name of the property that is about to change
propertyName, Object
the old value of the property
oldValue, Object
the new value of the property
newValue)

Reports a constrained property update to listeners that have been registered to track updates of all properties or a property with the specified name.

public void
fireVetoableChange(String
the programmatic name of the property that is about to change
propertyName, int
the old value of the property
oldValue, int
the new value of the property
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.

public void
fireVetoableChange(String
the programmatic name of the property that is about to change
propertyName, boolean
the old value of the property
oldValue, boolean
the new value of the property
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.

public void
fireVetoableChange(PropertyChangeEvent
the PropertyChangeEvent to be fired
event)

Fires a property change event to listeners that have been registered to track updates of all properties or a property with the specified name.

public VetoableChangeListener[]

Returns:

all of the VetoableChangeListeners added or an empty array if no listeners have been added
getVetoableChangeListeners()

Returns an array of all the listeners that were added to the VetoableChangeSupport object with addVetoableChangeListener().

public VetoableChangeListener[]

Returns:

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.
getVetoableChangeListeners(String
The name of the property being listened to
propertyName)

Returns an array of all the listeners which have been associated with the named property.

public boolean

Returns:

true if there are one or more listeners for the given property
hasListeners(String
the property name.
propertyName)

Check if there are any listeners for a specific property, including those registered on all properties.

private void
readObject(ObjectInputStream
the ObjectInputStream to read
s)

Reads the ObjectInputStream.

public void
removeVetoableChangeListener(VetoableChangeListener
The VetoableChangeListener to be removed
listener)

Remove a VetoableChangeListener from the listener list.

public void
removeVetoableChangeListener(String
The name of the property that was listened on.
propertyName, VetoableChangeListener
The VetoableChangeListener to be removed
listener)

Remove a VetoableChangeListener for a specific property.

private void
writeObject(ObjectOutputStream
the ObjectOutputStream to write
s)

Writes serializable fields to stream.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

mapback to summary
private VetoableChangeSupport.VetoableChangeListenerMap map
serialPersistentFieldsback to summary
private static final ObjectStreamField[] serialPersistentFields
Annotations
@Serial
Serial Fields:
children:Hashtable
The list of PropertyChangeListeners
source:Object
The object to be provided as the "source" for any generated events
vetoableChangeSupportSerializedDataVersion:int
The version
serialVersionUIDback to summary
private static final long serialVersionUID

Use serialVersionUID from JDK 1.1 for interoperability.

Annotations
@Serial
sourceback to summary
private Object source

The object to be provided as the "source" for any generated events.

Constructor Detail

VetoableChangeSupportback to summary
public VetoableChangeSupport(Object sourceBean)

Constructs a VetoableChangeSupport object.

Parameters
sourceBean:Object

The bean to be given as the source for any events.

Method Detail

addVetoableChangeListenerback to summary
public void addVetoableChangeListener(VetoableChangeListener listener)

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.

Parameters
listener:VetoableChangeListener

The VetoableChangeListener to be added

addVetoableChangeListenerback to summary
public void addVetoableChangeListener(String propertyName, VetoableChangeListener listener)

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.

Parameters
propertyName:String

The name of the property to listen on.

listener:VetoableChangeListener

The VetoableChangeListener to be added

Since
1.2
fireVetoableChangeback to summary
public void fireVetoableChange(String propertyName, Object oldValue, Object newValue) throws PropertyVetoException

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 PropertyVetoException to veto the update. If one of the listeners vetoes the update, this method passes a new "undo" PropertyChangeEvent that reverts to the old value to all listeners that already confirmed this update and throws the 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 fireVetoableChange(PropertyChangeEvent) method.

Parameters
propertyName:String

the programmatic name of the property that is about to change

oldValue:Object

the old value of the property

newValue:Object

the new value of the property

Exceptions
PropertyVetoException:
if one of listeners vetoes the property update
fireVetoableChangeback to summary
public void fireVetoableChange(String propertyName, int oldValue, int newValue) throws PropertyVetoException

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 PropertyVetoException to veto the update. If one of the listeners vetoes the update, this method passes a new "undo" PropertyChangeEvent that reverts to the old value to all listeners that already confirmed this update and throws the PropertyVetoException again.

No event is fired if old and new values are equal.

This is merely a convenience wrapper around the more general fireVetoableChange(String, Object, Object) method.

Parameters
propertyName:String

the programmatic name of the property that is about to change

oldValue:int

the old value of the property

newValue:int

the new value of the property

Exceptions
PropertyVetoException:
if one of listeners vetoes the property update
Since
1.2
fireVetoableChangeback to summary
public void fireVetoableChange(String propertyName, boolean oldValue, boolean newValue) throws PropertyVetoException

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 PropertyVetoException to veto the update. If one of the listeners vetoes the update, this method passes a new "undo" PropertyChangeEvent that reverts to the old value to all listeners that already confirmed this update and throws the PropertyVetoException again.

No event is fired if old and new values are equal.

This is merely a convenience wrapper around the more general fireVetoableChange(String, Object, Object) method.

Parameters
propertyName:String

the programmatic name of the property that is about to change

oldValue:boolean

the old value of the property

newValue:boolean

the new value of the property

Exceptions
PropertyVetoException:
if one of listeners vetoes the property update
Since
1.2
fireVetoableChangeback to summary
public void fireVetoableChange(PropertyChangeEvent event) throws PropertyVetoException

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 PropertyVetoException to veto the update. If one of the listeners vetoes the update, this method passes a new "undo" PropertyChangeEvent that reverts to the old value to all listeners that already confirmed this update and throws the PropertyVetoException again.

No event is fired if the given event's old and new values are equal and non-null.

Parameters
event:PropertyChangeEvent

the PropertyChangeEvent to be fired

Exceptions
PropertyVetoException:
if one of listeners vetoes the property update
Since
1.2
getVetoableChangeListenersback to summary
public VetoableChangeListener[] getVetoableChangeListeners()

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"
    }
  }
}
Returns:VetoableChangeListener[]

all of the VetoableChangeListeners added or an empty array if no listeners have been added

Since
1.4
See Also
VetoableChangeListenerProxy
getVetoableChangeListenersback to summary
public VetoableChangeListener[] getVetoableChangeListeners(String propertyName)

Returns an array of all the listeners which have been associated with the named property.

Parameters
propertyName:String

The name of the property being listened to

Returns:VetoableChangeListener[]

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
hasListenersback to summary
public boolean hasListeners(String propertyName)

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.

Parameters
propertyName:String

the property name.

Returns:boolean

true if there are one or more listeners for the given property

Since
1.2
readObjectback to summary
private void readObject(ObjectInputStream s) throws ClassNotFoundException, IOException

Reads the ObjectInputStream.

Parameters
s:ObjectInputStream

the ObjectInputStream to read

Annotations
@Serial
Exceptions
ClassNotFoundException:
if the class of a serialized object could not be found
IOException:
if an I/O error occurs
removeVetoableChangeListenerback to summary
public void removeVetoableChangeListener(VetoableChangeListener 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.

Parameters
listener:VetoableChangeListener

The VetoableChangeListener to be removed

removeVetoableChangeListenerback to summary
public void removeVetoableChangeListener(String propertyName, VetoableChangeListener 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.

Parameters
propertyName:String

The name of the property that was listened on.

listener:VetoableChangeListener

The VetoableChangeListener to be removed

Since
1.2
writeObjectback to summary
private void writeObject(ObjectOutputStream s) throws IOException

Writes serializable fields to stream.

Parameters
s:ObjectOutputStream

the ObjectOutputStream to write

Annotations
@Serial
Exceptions
IOException:
if an I/O error occurs
Serial data
Null terminated list of VetoableChangeListeners.

At serialization time we skip non-serializable listeners and only serialize the serializable listeners.

java.beans back to summary

private final Class VetoableChangeSupport.VetoableChangeListenerMap

extends ChangeListenerMap<VetoableChangeListener>
Class Inheritance
This is a ChangeListenerMap implementation that works with VetoableChangeListener objects.

Field Summary

Modifier and TypeField and Description
private static final VetoableChangeListener[]
EMPTY

Constructor Summary

AccessConstructor and Description
private
VetoableChangeListenerMap()

Method Summary

Modifier and TypeMethod and Description
public VetoableChangeListener
extract(VetoableChangeListener listener)

Implements abstract java.beans.ChangeListenerMap.extract.

Extracts a real listener from the proxy listener.
protected VetoableChangeListener[]

Returns:

an array with specified length
newArray(int
the array length
length)

Implements abstract java.beans.ChangeListenerMap.newArray.

Creates an array of VetoableChangeListener objects.
protected VetoableChangeListener

Returns:

a VetoableChangeListenerProxy object
newProxy(String
the name of the property to listen on
name, VetoableChangeListener
the listener to process events
listener)

Implements abstract java.beans.ChangeListenerMap.newProxy.

Creates a VetoableChangeListenerProxy object for the specified property.
Inherited from java.beans.ChangeListenerMap:
addgetgetEntriesgetListenersgetListenershasListenersremoveset

Field Detail

EMPTYback to summary
private static final VetoableChangeListener[] EMPTY

Constructor Detail

VetoableChangeListenerMapback to summary
private VetoableChangeListenerMap()

Method Detail

extractback to summary
public VetoableChangeListener extract(VetoableChangeListener listener)

Implements abstract java.beans.ChangeListenerMap.extract.

Doc from java.beans.ChangeListenerMap.extract.

Extracts a real listener from the proxy listener. It is necessary because default proxy class is not serializable.

Returns:VetoableChangeListener

a real listener

newArrayback to summary
protected VetoableChangeListener[] newArray(int length)

Implements abstract java.beans.ChangeListenerMap.newArray.

Creates an array of VetoableChangeListener objects. This method uses the same instance of the empty array when length equals 0.

Parameters
length:int

the array length

Returns:VetoableChangeListener[]

an array with specified length

Annotations
@Override
newProxyback to summary
protected VetoableChangeListener newProxy(String name, VetoableChangeListener listener)

Implements abstract java.beans.ChangeListenerMap.newProxy.

Creates a VetoableChangeListenerProxy object for the specified property.

Parameters
name:String

the name of the property to listen on

listener:VetoableChangeListener

the listener to process events

Returns:VetoableChangeListener

a VetoableChangeListenerProxy object

Annotations
@Override