The Java Beans API (Package java.

beans)

Contains classes related to developing beans -- components based on the

JavaBeans architecture.

Interface Summary

BeanInfo Use the BeanInfo interface to create a BeanInfo class and

provide explicit information about the methods, properties,
events, and other features of your beans.

Customizer A customizer class provides a complete custom GUI for

customizing a target Java Bean.

PropertyChangeListener A "PropertyChange" event gets fired whenever a bean

changes a "bound" property.

PropertyEditor A PropertyEditor class provides support for GUIs that want

to allow users to edit a property value of a given type.

VetoableChangeListener A VetoableChange event gets fired whenever a bean

changes a "constrained" property.

ExceptionListener An ExceptionListener is notified of internal exceptions.

Class Summary
BeanDescriptor A BeanDescriptor provides global information about a
"bean", including its Java class, its displayName, etc.

Beans This class provides some general purpose beans control

methods.

DefaultPersistenceDelegate The DefaultPersistenceDelegate is a concrete

implementation of the
abstract PersistenceDelegate class and is the delegate
used by default for classes about which no information is
available.

EventHandler The EventHandler class provides support for

dynamically generating event listeners whose methods
execute a simple statement involving an incoming event
object and a target object.

Introspector The Introspector class provides a standard way for tools

to learn about the properties, events, and methods
supported by a target Java Bean.

PersistenceDelegate The PersistenceDelegate class takes the responsibility

for expressing the state of an instance of a given class in
terms of the methods in the class's public API.

PropertyChangeEvent A "PropertyChange" event gets delivered whenever a

bean changes a "bound" or "constrained" property.

VetoableChangeSupport This is a utility class that can be used by beans that

support constrained properties.

Exception Summary
 IntrospectionException Thrown when an exception happens during Introspection.

PropertyVetoException A PropertyVetoException is thrown when a proposed change

to a property represents an unacceptable value.

A few of the classes are used by beans while they run in an application. For
example, the event classes are used by beans that fire property and vetoable
change events (eg. PropertyChangeEvent). However, most of the classes in this
package are meant to be used by a bean editor (that is, a development
environment for customizing and putting together beans to create an
application). In particular, these classes help the bean editor create a user
interface that the user can use to customize the bean. For example, a bean may
contain a property of a special type that a bean editor may not know how to
handle. By using the PropertyEditor interface, a bean developer can provide an
editor for this special type.

Long-Term Persistence

Java.beans package provides support for long-term persistence -- reading and

writing a bean as a textual representation of its property values. The property
values are treated as beans, and are recursively read or written to capture their
publicly available state. This approach is suitable for long-term storage because
it relies only on public API, rather than the likely-to-change private
implementation.

Writing out a bean, on the other hand, sometimes requires special knowledge of
the bean's type. If the bean's state can be expressed using only the no-argument
constructor and public getter and setter methods for properties, no special
knowledge is required.

Otherwise, the bean requires a custom persistence delegate -- an object that is in

charge of writing out beans of a particular type. All classes provided in the JDK
that descend from java.awt.Component, as well as all their properties,
automatically have persistence delegates.

If you need (or choose) to provide a persistence delegate for a bean, you can do
so either by using a DefaultPersistenceDelegate instance or by creating your own
subclass of PersistenceDelegate. If the only reason a bean needs a persistence
delegate is because you want to invoke the bean's constructor with property
values as arguments, you can create the bean's persistence delegate with the
one-argument DefaultPersistenceDelegate constructor. Otherwise, you need to
implement your own persistence delegate, for which you're likely to need the
following classes:

PersistenceDelegate
The abstract class from which all persistence delegates descend. Your
subclass should use its knowledge of the bean's type to provide
whatever Statements and Expressions are necessary to create the bean and
restore its state.
 Interface Customizer
A customizer class provides a complete custom GUI for customizing a target Java
Bean.

Each customizer should inherit from the java.awt.Component class so it can be

instantiated inside an AWT dialog or panel.

Each customizer should have a null constructor.

Method Details
 setObject

void setObject(Object bean)

Set the object to be customized. This method should be called only once, before
the Customizer has been added to any parent AWT container.
Parameters:

bean - The object to be customized.

 addPropertyChangeListener

void addPropertyChangeListener(PropertyChangeListener listener)

Register a listener for the PropertyChange event. The customizer should fire a
PropertyChange event whenever it changes the target bean in a way that might
require the displayed properties to be refreshed.
Parameters:

listener - An object to be invoked when a PropertyChange event is fired.

 removePropertyChangeListener

void removePropertyChangeListener(PropertyChangeListener listener)

Remove a listener for the PropertyChange event.

Parameters:

listener - The PropertyChange listener to be removed.

Properties
To define a property in a bean class, supply public getter and setter methods. For example, the
following methods define an int property called mouthWidth:

public class FaceBean {

private int mMouthWidth = 90;

public int getMouthWidth() {

return mMouthWidth;
}

public void setMouthWidth(int mw) {

mMouthWidth = mw;
}
}

A builder tool like NetBeans recognizes the method names and shows
the mouthWidth property in its list of properties. It also recognizes the type, int,
and provides an appropriate editor so the property can be manipulated at design
time.

This example shows a property than can be read and written. Other combinations
are also possible. A read-only property, for example, has a getter method but no
setter. A write-only property has a setter method only.

A special case for boolean properties allows the accessor method to be defined
using is instead of get. For example, the accessor for
a boolean property running could be as follows:

public boolean isRunning() {

// ...
}

Various specializations of basic properties are available and described in the following sections.

Indexed Properties

An indexed property is an array instead of a single value. In this case, the bean
class provides a method for getting and setting the entire array. Here is an
example for an int[] property called testGrades:

public int[] getTestGrades() {

return mTestGrades;
}

public void setTestGrades(int[] tg) {

mTestGrades = tg;
}
For indexed properties, the bean class also provides methods for getting
and setting a specific element of the array.

public int getTestGrades(int index) {

return mTestGrades[index];
}

public void setTestGrades(int index, int grade) {

mTestGrades[index] = grade;
}

Bound Properties

A bound property notifies listeners when its value changes. This has two
implications:

1. The bean class includes addPropertyChangeListener() and

removePropertyChangeListener() methods for managing the bean's
listeners.
2. When a bound property is changed, the bean sends
a PropertyChangeEvent to its registered listeners.

PropertyChangeEvent and PropertyChangeListener live in

the java.beans package.

The java.beans package also includes a class, PropertyChangeSupport,

that takes care of most of the work of bound properties. This handy class keeps
track of property listeners and includes a convenience method that fires property
change events to all registered listeners.
The following example shows how you could make the mouthWidth property a
bound property using PropertyChangeSupport. The necessary additions for
the bound property are shown in bold.

import java.beans.*;

public class FaceBean {

private int mMouthWidth = 90;
private PropertyChangeSupport mPcs =
new PropertyChangeSupport(this);

public int getMouthWidth() {

return mMouthWidth;
}

public void setMouthWidth(int mw) {

int oldMouthWidth = mMouthWidth;
mMouthWidth = mw;
mPcs.firePropertyChange("mouthWidth",
oldMouthWidth, mw);
}

public void
addPropertyChangeListener(PropertyChangeListener listener) {
mPcs.addPropertyChangeListener(listener);
}

public void
removePropertyChangeListener(PropertyChangeListener listener) {
mPcs.removePropertyChangeListener(listener);
}
}

Bound properties can be tied directly to other bean properties using a builder tool like NetBeans. You
could, for example, take the value property of a slider component and bind it to
the mouthWidth property shown in the example. NetBeans allows you to do this without writing any
code.
Constrained Properties

A constrained property is a special kind of bound property. For a constrained property, the bean keeps
track of a set of veto listeners. When a constrained property is about to change, the listeners are
consulted about the change. Any one of the listeners has a chance to veto the change, in which case
the property remains unchanged.

The veto listeners are separate from the property change listeners. Fortunately,
the java.beans package includes a VetoableChangeSupport class that greatly simplifies
constrained properties.

Changes to the mouthWidth example are shown in bold:

import java.beans.*;

public class FaceBean {

private int mMouthWidth = 90;
private PropertyChangeSupport mPcs =
new PropertyChangeSupport(this);
private VetoableChangeSupport mVcs =
new VetoableChangeSupport(this);

public int getMouthWidth() {

return mMouthWidth;
}

public void setMouthWidth(int mw) throws PropertyVetoException {

int oldMouthWidth = mMouthWidth;
mVcs.fireVetoableChange("mouthWidth",
oldMouthWidth, mw);
mMouthWidth = mw;
mPcs.firePropertyChange("mouthWidth",
oldMouthWidth, mw);
}

public void
addPropertyChangeListener(PropertyChangeListener listener) {
mPcs.addPropertyChangeListener(listener);
}

public void
removePropertyChangeListener(PropertyChangeListener listener) {
mPcs.removePropertyChangeListener(listener);
}

public void
addVetoableChangeListener(VetoableChangeListener listener) {
mVcs.addVetoableChangeListener(listener);
}

public void
removeVetoableChangeListener(VetoableChangeListener listener) {
mVcs.removeVetoableChangeListener(listener);
}
}