OpenJDK 1.22 · java.beans · APIdia, the JavaDoc alternative

Contains classes related to developing beans -- components based on the JavaBeans architecture. 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 (see java.beans.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.

To minimize the resources used by a bean, the classes used by bean editors are loaded only when the bean is being edited. They are not needed while the bean is running in an application and therefore not loaded. This information is kept in what's called a bean-info (see java.beans.BeanInfo).

Unless explicitly stated, null values or empty Strings are not valid parameters for the methods in this package. You may expect to see exceptions if these parameters are used.

Long-Term Persistence

As of v1.4, the 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.

Note: The persistence scheme cannot automatically instantiate custom inner classes, such as you might use for event handlers. By using the java.beans.EventHandler class instead of inner classes for custom event handlers, you can avoid this problem.

You read and write beans in XML format using the java.beans.XMLDecoder and java.beans.XMLEncoder classes, respectively. One notable feature of the persistence scheme is that reading in a bean requires no special knowledge of the bean.

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 java.beans.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:

java.beans.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.
java.beans.Statement: Represents the invocation of a single method on an object. Includes a set of arguments to the method.
java.beans.Expression: A subclass of Statement used for methods that return a value.

Once you create a persistence delegate, you register it using the setPersistenceDelegate method of XMLEncoder.

Interface Summary

Modifier and Type	Interface and Description
public interface	AppletInitializer Deprecated for removal since 9. The Applet API is deprecated. See the java.applet package documentation for further information. This interface is designed to work in collusion with java.beans.Beans.instantiate.
public interface	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.
public interface	Customizer A customizer class provides a complete custom GUI for customizing a target Java Bean.
public interface	DesignMode This interface is intended to be implemented by, or delegated from, instances of java.beans.beancontext.BeanContext, in order to propagate to its nested hierarchy of java.beans.beancontext.BeanContextChild instances, the current "designTime" property.
public interface	ExceptionListener An ExceptionListener is notified of internal exceptions.
public interface	PropertyChangeListener A "PropertyChange" event gets fired whenever a bean changes a "bound" property.
public interface	PropertyEditor A PropertyEditor class provides support for GUIs that want to allow users to edit a property value of a given type.
public interface	VetoableChangeListener A VetoableChange event gets fired whenever a bean changes a "constrained" property.
public interface	Visibility Under some circumstances a bean may be run on servers where a GUI is not available.

Annotation Summary

Modifier and Type	Annotation and Description
public @interface	BeanProperty An annotation used to specify some property-related information for the automatically generated `BeanInfo` classes.
public @interface	ConstructorProperties An annotation on a constructor that shows how the parameters of that constructor correspond to the constructed object's getter methods.
public @interface	JavaBean An annotation used to specify some class-related information for the automatically generated `BeanInfo` classes.
public @interface	Transient Indicates that an attribute called "transient" should be declared with the given `value` when the `Introspector` constructs a `PropertyDescriptor` or `EventSetDescriptor` classes associated with the annotated code element.

Class Summary

Modifier and Type	Class and Description
public class	BeanDescriptor A BeanDescriptor provides global information about a "bean", including its Java class, its displayName, etc. This is one of the kinds of descriptor returned by a BeanInfo object, which also returns descriptors for properties, method, and events.
public class	Beans This class provides some general purpose beans control methods.
pack-priv class	BeansAppletContext Deprecated for removal since 9. Package private support class.
pack-priv class	BeansAppletStub Deprecated for removal since 9. Package private support class.
pack-priv abstract class	ChangeListenerMap<L extends EventListener> This is an abstract class that provides base functionality for the `PropertyChangeSupport` class and the `VetoableChangeSupport` class.
public class	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.
public class	Encoder An `Encoder` is a class which can be used to create files or streams that encode the state of a collection of JavaBeans in terms of their public APIs.
public class	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.
public class	EventSetDescriptor An EventSetDescriptor describes a group of events that a given Java bean fires.
public class	Expression An `Expression` object represents a primitive expression in which a single method is applied to a target and a set of arguments to return a result - as in `"a.getFoo()"`.
public class	FeatureDescriptor The FeatureDescriptor class is the common baseclass for PropertyDescriptor, EventSetDescriptor, and MethodDescriptor, etc. It supports some common information that can be set and retrieved for any of the introspection descriptors.
pack-priv class	GenericBeanInfo Package private implementation support class for Introspector's internal use.
public class	IndexedPropertyChangeEvent An "IndexedPropertyChange" event gets delivered whenever a component that conforms to the JavaBeans specification (a "bean") changes a bound indexed property.
public class	IndexedPropertyDescriptor An IndexedPropertyDescriptor describes a property that acts like an array and has an indexed read and/or indexed write method to access specific elements of the array.
public class	IntrospectionException Thrown when an exception happens during Introspection.
public class	Introspector The Introspector class provides a standard way for tools to learn about the properties, events, and methods supported by a target Java Bean.
pack-priv class	MetaData
public class	MethodDescriptor A MethodDescriptor describes a particular method that a Java Bean supports for external access from other components.
pack-priv class	MethodRef
pack-priv class	NameGenerator A utility class which generates unique names for object instances.
pack-priv class	ObjectInputStreamWithLoader This subclass of ObjectInputStream delegates loading of classes to an existing ClassLoader.
public class	ParameterDescriptor The ParameterDescriptor class allows bean implementors to provide additional information on each of their parameters, beyond the low level type information provided by the java.lang.reflect.Method class.
public abstract class	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.
public class	PropertyChangeEvent A "PropertyChange" event gets delivered whenever a bean changes a "bound" or "constrained" property.
public class	PropertyChangeListenerProxy A class which extends the `EventListenerProxy` specifically for adding a `PropertyChangeListener` with a "bound" property.
public class	PropertyChangeSupport This is a utility class that can be used by beans that support bound properties.
public class	PropertyDescriptor A PropertyDescriptor describes one property that a Java Bean exports via a pair of accessor methods.
public class	PropertyEditorManager The PropertyEditorManager can be used to locate a property editor for any given type name.
public class	PropertyEditorSupport This is a support class to help build property editors.
public class	PropertyVetoException A PropertyVetoException is thrown when a proposed change to a property represents an unacceptable value.
public class	SimpleBeanInfo This is a support class to make it easier for people to provide BeanInfo classes.
public class	Statement A `Statement` object represents a primitive statement in which a single method is applied to a target and a set of arguments - as in `"a.setFoo(b)"`.
pack-priv class	ThreadGroupContext The `ThreadGroupContext` is an application-dependent context referenced by the specific `ThreadGroup`.
public class	VetoableChangeListenerProxy A class which extends the `EventListenerProxy` specifically for adding a `VetoableChangeListener` with a "constrained" property.
public class	VetoableChangeSupport This is a utility class that can be used by beans that support constrained properties.
pack-priv abstract class	WeakIdentityMap<T> Hash table based mapping, which uses weak references to store keys and reference-equality in place of object-equality to compare them.
public class	XMLDecoder The `XMLDecoder` class is used to read XML documents created using the `XMLEncoder` and is used just like the `ObjectInputStream`.
public class	XMLEncoder The `XMLEncoder` class is a complementary alternative to the `ObjectOutputStream` and can used to generate a textual representation of a JavaBean in the same way that the `ObjectOutputStream` can be used to create binary representation of `Serializable` objects.

Package java.beans

Long-Term Persistence

Related Documentation

Interface Summary

Annotation Summary

Class Summary