Java Doc for AbstractBean.java in  » Swing-Library » swingx » org » jdesktop » beans » Java Source Code / Java DocumentationJava Source Code and Java Documentation

A convenience class from which to extend all non-visual JavaBeans. It manages the PropertyChange notification system, making it relatively trivial to add support for property change events in getters/setters.

A non-visual java bean is a Java class that conforms to the JavaBean patterns to allow visual manipulation of the bean's properties and event handlers at design-time.

Here is a simple example bean that contains one property, foo, and the proper pattern for implementing property change notification:

 public class ABean extends JavaBean {
 private String foo;
 public void setFoo(String newFoo) {
 String old = getFoo();
 this.foo = newFoo;
 firePropertyChange("foo", old, getFoo());
 }
 public String getFoo() {
 return foo;
 }
 }
 

You will notice that "getFoo()" is used in the setFoo method rather than accessing "foo" directly for the gets. This is done intentionally so that if a subclass overrides getFoo() to return, for instance, a constant value the property change notification system will continue to work properly.

The firePropertyChange method takes into account the old value and the new value. Only if the two differ will it fire a property change event. So you can be assured from the above code fragment that a property change event will only occur if old is indeed different from getFoo()

JavaBean also supports VetoablePropertyChange events. These events are similar to PropertyChange events, except a special exception can be used to veto changing the property. For example, perhaps the property is changing from "fred" to "red", but a listener deems that "red" is unexceptable. In this case, the listener can fire a veto exception and the property must remain "fred". For example:

 public class ABean extends JavaBean {
 private String foo;
 public void setFoo(String newFoo) throws PropertyVetoException {
 String old = getFoo();
 this.foo = newFoo;
 fireVetoableChange("foo", old, getFoo());
 }
 public String getFoo() {
 return foo;
 }
 }
 public class Tester {
 public static void main(String... args) {
 try {
 ABean a = new ABean();
 a.setFoo("fred");
 a.addVetoableChangeListener(new VetoableChangeListener() {
 public void vetoableChange(PropertyChangeEvent evt) throws PropertyVetoException {
 if ("red".equals(evt.getNewValue()) {
 throw new PropertyVetoException("Cannot be red!", evt);
 }
 }
 }
 a.setFoo("red");
 } catch (Exception e) {
 e.printStackTrace(); // this will be executed
 }
 }
 }
 

If some listeners have been added with a named property, then the returned array will be a mixture of PropertyChangeListeners and PropertyChangeListenerProxys.

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

This is merely a convenience wrapper around the more general firePropertyChange method that takes PropertyChangeEvent value.
Parameters:
  propertyName - The programmatic name of the property thatwas changed.
Parameters:
  index - index of the property element that was changed.
Parameters:
  oldValue - The old value of the property.
Parameters:
  newValue - The new value of the property.

This is merely a convenience wrapper around the more general firePropertyChange method that takes PropertyChangeEvent value.
Parameters:
  propertyName - The programmatic name of the propertythat was changed.
Parameters:
  oldValue - The old value of the property.
Parameters:
  newValue - The new value of the property.

No event is fired if old and new are equal and non-null.
Parameters:
  propertyName - The programmatic name of the propertythat is about to change..
Parameters:
  oldValue - The old value of the property.
Parameters:
  newValue - The new value of the property.
exception:
  PropertyVetoException - if the recipient wishes the propertychange to be rolled back.

No event is fired if old and new are equal and non-null.
Parameters:
  evt - The PropertyChangeEvent to be fired.
exception:
  PropertyVetoException - if the recipient wishes the propertychange to be rolled back.

If some listeners have been added with a named property, then the returned array will be a mixture of PropertyChangeListeners and PropertyChangeListenerProxys. If the calling method is interested in distinguishing the listeners then it must test each element to see if it's a PropertyChangeListenerProxy, perform the cast, and examine the parameter.

 PropertyChangeListener[] listeners = bean.getPropertyChangeListeners();
 for (int i = 0; i < listeners.length; i++) {
 if (listeners[i] instanceof PropertyChangeListenerProxy) {
 PropertyChangeListenerProxy proxy = 
 (PropertyChangeListenerProxy)listeners[i];
 if (proxy.getPropertyName().equals("foo")) {
 // proxy is a PropertyChangeListener which was associated
 // with the property named "foo"
 }
 }
 }
 

List of VetoableChangeListeners and VetoableChangeListenerProxysif named property change listeners were added.