The java.beans Package (Java in a Nutshell)

The java.beans package contains classes and interfaces related to JavaBeans components. Most of the classes and interfaces are used by tools that manipulate beans, rather than by the beans themselves. They are also used or implemented by auxiliary classes provided by bean implementors for the benefit of bean-manipulation tools. Figure 9-1 shows the class hierarchy for this package.

Figure 9-1. The java.beans package

The Beans class defines several generally useful static methods. Its instantiate() method is particularly important. The Introspector class is used to obtain information about a bean and the properties, events, and methods it exports. Most of this information is returned using the FeatureDescriptor class and its various subclasses. The java.beans package also defines the PropertyChangeEvent class and the PropertyChangeListener interface that are widely used by AWT and Swing to provide notification when a bound property of a GUI component changes.

See Chapter 6, "JavaBeans", for a complete introduction to the JavaBeans component model.

AppletInitializer

Java 1.2

java.beans

This interface defines general methods to initialize a newly instantiated Applet object. An AppletInitializer can be passed to the Beans.instantiate() method so that when a bean that is also an applet is created, it can be properly initialized. The initialize() method should associate the applet object with an appropriate AppletContext and AppletStub, place it within an appropriate Container, and call its init() method. The activate() method should make the applet active by calling its start() method. This interface is typically used by bean context implementors. Applications writers may need to use AppletInitializer objects, but should not usually have to invoke or implement the methods directly.

public interface AppletInitializer {
//	Public Instance Methods
	public abstract void activate (java.applet.Applet newApplet);
	public abstract void initialize (java.applet.Applet newAppletBean, java.beans.beancontext.BeanContext bCtxt);
}

Passed To: Beans.instantiate()

BeanDescriptor

Java 1.1

java.beans

PJ1.1

A BeanDescriptor object is a type of FeatureDescriptor that describes a JavaBeans component. The BeanInfo class for a bean optionally creates and initializes a BeanDescriptor object to describe the bean. Typically, only application builders and similar tools use the BeanDescriptor. To create a BeanDescriptor, you must specify the class of the bean and, optionally, the class of a Customizer for the bean. You can use the methods of FeatureDescriptor to provide additional information about the bean.

public class BeanDescriptor extends FeatureDescriptor {
//	Public Constructors
	public BeanDescriptor (Class beanClass);
	public BeanDescriptor (Class beanClass, Class customizerClass);
//	Public Instance Methods
	public Class getBeanClass ();
	public Class getCustomizerClass ();
}

Hierarchy: Object-->FeatureDescriptor-->BeanDescriptor

Returned By: BeanInfo.getBeanDescriptor(), SimpleBeanInfo.getBeanDescriptor()

BeanInfo

Java 1.1

java.beans

PJ1.1

The BeanInfo interface defines the methods a class must implement in order to export information about a JavaBeans component. The Introspector class knows how to obtain all the basic information required about a bean. A bean that wants to be more programmer-friendly can provide a class that implements this interface, and provide additional information about itself (such as an icon and description strings for each of its properties, events, and methods). Note that a bean developer defines a class that implements the methods of this interface. Typically, only builder applications and similar tools actually invoke the methods defined here.

The getBeanDescriptor(), getEventSetDescriptors(), getPropertyDescriptors(), and getMethodDescriptors() methods should return appropriate descriptor objects for the bean or null if the bean does not provide explicit bean, event set, property, or method descriptor objects. The getDefaultEventIndex() and getDefaultPropertyIndex() methods return values that specify the default event and property (i.e., those most likely to be of interest to a programmer using the bean). These methods should return -1 if there are no defaults. The getIcon() method should return an image object suitable for representing the bean in a palette or menu of available beans. The argument passed to this method is one of the four constants defined by the class; it specifies the type and size of icon requested. If the requested icon cannot be provided, getIcon() should return null.

A BeanInfo class is allowed to return null or -1 if it cannot provide the requested information. In this case, the Introspector class provides basic values for the omitted information from its own introspection of the bean. See SimpleBeanInfo for a trivial implementation of this interface suitable for convenient subclassing.

public interface BeanInfo {
//	Public Constants
	public static final int ICON_COLOR_16x16 ;	=1
	public static final int ICON_COLOR_32x32 ;	=2
	public static final int ICON_MONO_16x16 ;	=3
	public static final int ICON_MONO_32x32 ;	=4
//	Property Accessor Methods (by property name)
	public abstract BeanInfo[ ] getAdditionalBeanInfo ();
	public abstract BeanDescriptor getBeanDescriptor ();
	public abstract int getDefaultEventIndex ();
	public abstract int getDefaultPropertyIndex ();
	public abstract EventSetDescriptor[ ] getEventSetDescriptors ();
	public abstract MethodDescriptor[ ] getMethodDescriptors ();
	public abstract PropertyDescriptor[ ] getPropertyDescriptors ();
//	Public Instance Methods
	public abstract java.awt.Image getIcon (int iconKind);
}

Implementations: SimpleBeanInfo, java.beans.beancontext.BeanContextServiceProviderBeanInfo

Returned By: BeanInfo.getAdditionalBeanInfo(), Introspector.getBeanInfo(), SimpleBeanInfo.getAdditionalBeanInfo(), java.beans.beancontext.BeanContextServiceProviderBeanInfo.getServicesBeanInfo()

Beans

Java 1.1

java.beans

PJ1.1

The Beans class is not meant to be instantiated; its static methods provide miscellaneous JavaBeans features. The instantiate() method creates an instance of a bean. The specified bean name represents either a serialized bean file or a bean class file; it is interpreted relative to the specified ClassLoader object.

The setDesignTime() and isDesignTime() methods can set and query a flag that indicates whether beans are being used in a application builder environment. Similarly, setGuiAvailable() and isGuiAvailable() set and query a flag that indicates whether the Java Virtual Machine is running in an environment in which a GUI is available. (Note that untrusted applet code cannot call setDesignTime() or setGuiAvailable().)

The isInstanceOf() method is a replacement for the Java instanceof operator to use with beans. Currently, it behaves like instanceof, but in the future it may work with beans that consist of a set of Java objects, each of which provides a different view of a bean. Similarly, the getInstanceOf() method is a replacement for the Java cast operator. This method converts a bean to a superclass or interface type, and currently, it behaves like a cast, but in the future, it will be compatible with multiclass beans.

public class Beans {
//	Public Constructors
	public Beans ();
//	Public Class Methods
	public static Object getInstanceOf (Object bean, Class targetType);
	public static Object instantiate (ClassLoader cls, String beanName) throws java.io.IOExceptionClassNotFoundException;
1.2	public static Object instantiate (ClassLoader cls, String beanName, java.beans.beancontext.BeanContext beanContext) throws java.io.IOExceptionClassNotFoundException;
1.2	public static Object instantiate (ClassLoader cls, String beanName, java.beans.beancontext.BeanContext beanContext, AppletInitializer initializer) throws java.io.IOExceptionClassNotFoundException;
	public static boolean isDesignTime ();
	public static boolean isGuiAvailable ();
	public static boolean isInstanceOf (Object bean, Class targetType);
	public static void setDesignTime (boolean isDesignTime) throws SecurityException;
	public static void setGuiAvailable (boolean isGuiAvailable) throws SecurityException;
}

Customizer

Java 1.1

java.beans

PJ1.1

The Customizer interface specifies the methods that must be defined by any class designed to customize a JavaBeans component. In addition to implementing this interface, a customizer class must be a subclass of java.awt.Component and have a constructor that takes no arguments so it can be instantiated by an application builder.

Customizer classes are typically used by a complex bean to allow the user to easily configure the bean and provide an alternative to a simple list of properties and their values. If a customizer class is defined for a bean, it must be associated with the bean through a BeanDescriptor object returned by a BeanInfo class for the bean. Note that while a Customizer class is created by the author of a bean, that class is instantiated and used only by application builders and similar tools.

After a Customizer class is instantiated, its setObject() method is invoked once to specify the bean object to customize. The addPropertyChangeListener() and removePropertyChangeListener() methods can be called to register and deregister PropertyChangeListener objects. The Customizer should send a PropertyChangeEvent to all registered listeners any time it changes a property of the bean it is customizing.

public interface Customizer {
//	Event Registration Methods (by event name)
	public abstract void addPropertyChangeListener (PropertyChangeListener listener);
	public abstract void removePropertyChangeListener (PropertyChangeListener listener);
//	Public Instance Methods
	public abstract void setObject (Object bean);
}

DesignMode

Java 1.2

java.beans

This interface defines a single boolean designTime property that specifies whether a bean is running within an interactive design tool or a standalone application or applet. This interface is typically implemented by a bean container or bean context, so that children beans can query the designTime property.

public interface DesignMode {
//	Public Constants
	public static final String PROPERTYNAME ;	="designTime"
//	Public Instance Methods
	public abstract boolean isDesignTime ();
	public abstract void setDesignTime (boolean designTime);
}

Implementations: java.beans.beancontext.BeanContext

EventSetDescriptor

Java 1.1

java.beans

PJ1.1

An EventSetDescriptor object is a type of FeatureDescriptor that describes a single set of events supported by a JavaBeans component. A set of events corresponds to one or more methods supported by a single EventListener interface. The BeanInfo class for a bean optionally creates EventSetDescriptor objects to describe the event sets the bean supports. Typically, only application builders and similar tools use the get and is methods of EventSetDescriptor objects to obtain the event-set description information.

To create an EventSetDescriptor object, you must specify the class of the bean that supports the event set, the base name of the event set, the class of the EventListener interface that corresponds to the event set, and the methods within this interface that are invoked when particular events within the set occur. Optionally, you can also specify the methods of the bean class that add and remove EventListener objects. The various constructors allow you to specify methods by name, as java.lang.reflect.Method objects, or as MethodDescriptor objects.

Once you have created an EventSetDescriptor, use setUnicast() to specify whether it represents a unicast event and setInDefaultEventSet() to specify whether the event set should be treated as the default event set by builder applications. The methods of the FeatureDescriptor superclass allow additional information about the property to be specified.

public class EventSetDescriptor extends FeatureDescriptor {
//	Public Constructors
	public EventSetDescriptor (Class sourceClass, String eventSetName, Class listenerType, String listenerMethodName) throws IntrospectionException;
	public EventSetDescriptor (String eventSetName, Class listenerType, MethodDescriptor[ ] listenerMethodDescriptors, java.lang.reflect.Method addListenerMethod, java.lang.reflect.Method removeListenerMethod) throws IntrospectionException;
	public EventSetDescriptor (String eventSetName, Class listenerType, java.lang.reflect.Method[ ] listenerMethods, java.lang.reflect.Method addListenerMethod, java.lang.reflect.Method removeListenerMethod) throws IntrospectionException;
	public EventSetDescriptor (Class sourceClass, String eventSetName, Class listenerType, String[ ] listenerMethodNames, String addListenerMethodName, String removeListenerMethodName) throws IntrospectionException;
//	Property Accessor Methods (by property name)
	public java.lang.reflect.Method getAddListenerMethod ();
	public boolean isInDefaultEventSet ();
	public void setInDefaultEventSet (boolean inDefaultEventSet);
	public MethodDescriptor[ ] getListenerMethodDescriptors ();
	public java.lang.reflect.Method[ ] getListenerMethods ();
	public Class getListenerType ();
	public java.lang.reflect.Method getRemoveListenerMethod ();
	public boolean isUnicast ();
	public void setUnicast (boolean unicast);
}

Hierarchy: Object-->FeatureDescriptor-->EventSetDescriptor

Returned By: BeanInfo.getEventSetDescriptors(), SimpleBeanInfo.getEventSetDescriptors()

FeatureDescriptor

Java 1.1

java.beans

PJ1.1

The FeatureDescriptor class is the base class for MethodDescriptor and PropertyDescriptor, as well as other classes used by the JavaBeans introspection mechanism. It provides basic information about a feature (e.g., method, property, or event) of a bean. Typically, the methods that begin with get and is are used by application builders or other tools to query the features of a bean. The set methods, on the other hand, may be used by bean authors to define information about the bean.

setName() specifies the locale-independent, programmatic name of the feature; setDisplayName() specifies a localized, human-readable name; and setShortDescription() specifies a short localized string (about 40 characters) that describes the feature. Both the short description and the localized name default to the value of the programmatic name. setExpert() and setHidden() allow you to indicate that the feature is for use only by experts or by the builder tool and should be hidden from users of the builder. Finally, the setValue() method allows you to associate an arbitrary named value with the feature.

public class FeatureDescriptor {
//	Public Constructors
	public FeatureDescriptor ();
//	Property Accessor Methods (by property name)
	public String getDisplayName ();	default:null
	public void setDisplayName (String displayName);
	public boolean isExpert ();	default:false
	public void setExpert (boolean expert);
	public boolean isHidden ();	default:false
	public void setHidden (boolean hidden);
	public String getName ();	default:null
	public void setName (String name);
1.2	public boolean isPreferred ();	default:false
1.2	public void setPreferred (boolean preferred);
	public String getShortDescription ();	default:null
	public void setShortDescription (String text);
//	Public Instance Methods
	public java.util.Enumeration attributeNames ();
	public Object getValue (String attributeName);
	public void setValue (String attributeName, Object value);
}

Subclasses: BeanDescriptor, EventSetDescriptor, MethodDescriptor, ParameterDescriptor, PropertyDescriptor

IndexedPropertyDescriptor

Java 1.1

java.beans

PJ1.1

An IndexedPropertyDescriptor object is a type of PropertyDescriptor that describes a bean property that is (or behaves like) an array. The BeanInfo class for a bean optionally creates and initializes IndexedPropertyDescriptor objects to describe the indexed properties the bean supports. Typically, only application builders and similar tools use the descriptor objects to obtain indexed property description information.

You create an IndexedPropertyDescriptor by specifying the name of the indexed property and the Class object for the bean. If you have not followed the standard design patterns for accessor method naming, you can also specify the accessor methods for the property, either as method names or as java.lang.reflect.Method objects. Once you have created an IndexedPropertyDescriptor object, you can use the methods of PropertyDescriptor and FeatureDescriptor to provide additional information about the indexed property.

public class IndexedPropertyDescriptor extends PropertyDescriptor {
//	Public Constructors
	public IndexedPropertyDescriptor (String propertyName, Class beanClass) throws IntrospectionException;
	public IndexedPropertyDescriptor (String propertyName, java.lang.reflect.Method getter, java.lang.reflect.Method setter, java.lang.reflect.Method indexedGetter, java.lang.reflect.Method indexedSetter) throws IntrospectionException;
	public IndexedPropertyDescriptor (String propertyName, Class beanClass, String getterName, String setterName, String indexedGetterName, String indexedSetterName) throws IntrospectionException;
//	Public Instance Methods
	public Class getIndexedPropertyType ();
	public java.lang.reflect.Method getIndexedReadMethod ();
	public java.lang.reflect.Method getIndexedWriteMethod ();
1.2	public void setIndexedReadMethod (java.lang.reflect.Method getter) throws IntrospectionException;
1.2	public void setIndexedWriteMethod (java.lang.reflect.Method setter) throws IntrospectionException;
}

Hierarchy: Object-->FeatureDescriptor-->PropertyDescriptor-->IndexedPropertyDescriptor

IntrospectionException

Java 1.1

java.beans

serializable checked PJ1.1

Signals that introspection on a JavaBeans component cannot be completed. Typically, this indicates a bug in the way the bean or its associated BeanInfo class is defined.

public class IntrospectionException extends Exception {
//	Public Constructors
	public IntrospectionException (String mess);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IntrospectionException

Thrown By: Too many methods to list.

Introspector

Java 1.1

java.beans

PJ1.1

The Introspector is a class that is never instantiated. Its static getBeanInfo() methods provide a way to obtain information about a JavaBeans component and are typically only invoked by application builders or similar tools. getBeanInfo() first looks for a BeanInfo class for the specified bean class. For a class named x, it looks for a BeanInfo class named xBeanInfo, first in the current package and then in each of the packages in the BeanInfo search path.

If no BeanInfo class is found, or if the BeanInfo class found does not provide complete information about the bean properties, events, and methods, getBeanInfo() introspects on the bean class by using the java.lang.reflect package to fill in the missing information. When explicit information is provided by a BeanInfo class, getBeanInfo() treats it as definitive. When determining information through introspection, however, it examines each of the bean's superclasses in turn, looking for a BeanInfo class at that level or using introspection. When calling getBeanInfo(), you may optionally specify a second class argument that specifies a superclass for which, and above which, getBeanInfo() does not introspect.

public class Introspector {
//	No Constructor
//	Public Constants
1.2	public static final int IGNORE_ALL_BEANINFO ;	=3
1.2	public static final int IGNORE_IMMEDIATE_BEANINFO ;	=2
1.2	public static final int USE_ALL_BEANINFO ;	=1
//	Public Class Methods
	public static String decapitalize (String name);
1.2	public static void flushCaches ();
1.2	public static void flushFromCaches (Class clz);
	public static BeanInfo getBeanInfo (Class beanClass) throws IntrospectionException;
1.2	public static BeanInfo getBeanInfo (Class beanClass, int flags) throws IntrospectionException;
	public static BeanInfo getBeanInfo (Class beanClass, Class stopClass) throws IntrospectionException;
	public static String[ ] getBeanInfoSearchPath ();	synchronized
	public static void setBeanInfoSearchPath (String[ ] path);	synchronized
}

MethodDescriptor

Java 1.1

java.beans

PJ1.1

A MethodDescriptor object is a type of FeatureDescriptor that describes a method supported by a JavaBeans component. The BeanInfo class for a bean optionally creates MethodDescriptor objects that describe the methods the bean exports. While a BeanInfo class creates and initializes MethodDescriptor objects, it is typically only application builders and similar tools that use these objects to obtain information about the methods supported by a bean.

To create a MethodDescriptor, you must specify the java.lang.reflect.Method object for the method and, optionally, an array of ParameterDescriptor objects that describe the parameters of the method. Once you have created a MethodDescriptor object, you can use FeatureDescriptor methods to provide additional information about each method.

public class MethodDescriptor extends FeatureDescriptor {
//	Public Constructors
	public MethodDescriptor (java.lang.reflect.Method method);
	public MethodDescriptor (java.lang.reflect.Method method, ParameterDescriptor[ ] parameterDescriptors);
//	Public Instance Methods
	public java.lang.reflect.Method getMethod ();
	public ParameterDescriptor[ ] getParameterDescriptors ();
}

Hierarchy: Object-->FeatureDescriptor-->MethodDescriptor

Passed To: EventSetDescriptor.EventSetDescriptor()

Returned By: BeanInfo.getMethodDescriptors(), EventSetDescriptor.getListenerMethodDescriptors(), SimpleBeanInfo.getMethodDescriptors()

ParameterDescriptor

Java 1.1

java.beans

PJ1.1

A ParameterDescriptor object is a type of FeatureDescriptor that describes an argument or parameter to a method of a JavaBeans component. The BeanInfo class for a JavaBeans component optionally creates ParameterDescriptor objects that describe the parameters of the methods the bean exports. While the BeanInfo class creates and initializes ParameterDescriptor objects, it is typically only application builders and similar tools that use these objects to obtain information about method parameters supported by the bean.

The ParameterDescriptor class is a trivial subclass of FeatureDescriptor and does not provide any new methods. Thus, you should use the methods of FeatureDescriptor to provide information about method parameters.

public class ParameterDescriptor extends FeatureDescriptor {
//	Public Constructors
	public ParameterDescriptor ();
}

Hierarchy: Object-->FeatureDescriptor-->ParameterDescriptor

Passed To: MethodDescriptor.MethodDescriptor()

Returned By: MethodDescriptor.getParameterDescriptors()

PropertyChangeEvent

Java 1.1

java.beans

serializable event PJ1.1

PropertyChangeEvent is a subclass of java.util.EventObject. An event of this type is sent to interested PropertyChangeListener objects whenever a JavaBeans component changes a bound property or whenever a PropertyEditor or Customizer changes a property value. A PropertyChangeEvent is also sent to registered VetoableChangeListener objects when a bean attempts to change the value of a constrained property.

When creating a PropertyChangeEvent, you normally specify the bean that generated the event, the programmatic (locale-independent) name of the property that changed, and the old and new values of the property. If the values cannot be determined, null should be passed instead. If the event is a notification that more than one property value changed, the name should also be null. While JavaBeans must generate and send PropertyChangeEvent objects, it is typically only application builders and similar tools that are interested in receiving them.

public class PropertyChangeEvent extends java.util.EventObject {
//	Public Constructors
	public PropertyChangeEvent (Object source, String propertyName, Object oldValue, Object newValue);
//	Public Instance Methods
	public Object getNewValue ();
	public Object getOldValue ();
	public Object getPropagationId ();
	public String getPropertyName ();
	public void setPropagationId (Object propagationId);
}

Hierarchy: Object-->java.util.EventObject(Serializable)-->PropertyChangeEvent

Passed To: PropertyChangeListener.propertyChange(), PropertyChangeSupport.firePropertyChange(), PropertyVetoException.PropertyVetoException(), VetoableChangeListener.vetoableChange(), VetoableChangeSupport.fireVetoableChange(), java.beans.beancontext.BeanContextSupport.{propertyChange(), vetoableChange()}, javax.swing.JList.AccessibleJList.propertyChange(), javax.swing.JTable.AccessibleJTable.propertyChange(), javax.swing.event.SwingPropertyChangeSupport.firePropertyChange(), javax.swing.table.DefaultTableColumnModel.propertyChange()

Returned By: PropertyVetoException.getPropertyChangeEvent()

PropertyChangeListener

Java 1.1

java.beans

event listener PJ1.1

This interface is an extension of java.util.EventListener; it defines the method a class must implement in order to be notified when property changes occur. A PropertyChangeEvent is sent to all registered PropertyChangeListener objects when a bean changes one of its bound properties or when a PropertyEditor or Customizer changes the value of a property.

public interface PropertyChangeListener extends java.util.EventListener {
//	Public Instance Methods
	public abstract void propertyChange (PropertyChangeEvent evt);
}

Hierarchy: (PropertyChangeListener(java.util.EventListener))

Implementations: java.beans.beancontext.BeanContextSupport, javax.swing.JList.AccessibleJList, javax.swing.JTable.AccessibleJTable, javax.swing.table.DefaultTableColumnModel

Passed To: Too many methods to list.

Returned By: java.beans.beancontext.BeanContextSupport.getChildPropertyChangeListener(), javax.swing.AbstractButton.createActionPropertyChangeListener(), javax.swing.JCheckBox.createActionPropertyChangeListener(), javax.swing.JComboBox.createActionPropertyChangeListener(), javax.swing.JMenu.createActionChangeListener(), javax.swing.JMenuItem.createActionPropertyChangeListener(), javax.swing.JPopupMenu.createActionChangeListener(), javax.swing.JRadioButton.createActionPropertyChangeListener(), javax.swing.JTextField.createActionPropertyChangeListener(), javax.swing.JToolBar.createActionChangeListener()

PropertyChangeSupport

Java 1.1

java.beans

serializable PJ1.1

The PropertyChangeSupport class is a convenience class that maintains a list of registered PropertyChangeListener objects and provides the firePropertyChange() method for sending a PropertyChangeEvent object to all registered listeners. Because there are some tricky thread-synchronization issues involved in doing this correctly, it is recommended that all JavaBeans that support bound properties either extend this class or, more commonly, create an instance of this class to which they can delegate the task of maintaining the list of listeners.

public class PropertyChangeSupport implements Serializable {
//	Public Constructors
	public PropertyChangeSupport (Object sourceBean);
//	Event Registration Methods (by event name)
	public void addPropertyChangeListener (PropertyChangeListener listener);	synchronized
	public void removePropertyChangeListener (PropertyChangeListener listener);	synchronized
//	Public Instance Methods
1.2	public void addPropertyChangeListener (String propertyName, PropertyChangeListener listener);	synchronized
1.2	public void firePropertyChange (PropertyChangeEvent evt);
1.2	public void firePropertyChange (String propertyName, int oldValue, int newValue);
1.2	public void firePropertyChange (String propertyName, boolean oldValue, boolean newValue);
	public void firePropertyChange (String propertyName, Object oldValue, Object newValue);
1.2	public boolean hasListeners (String propertyName);	synchronized
1.2	public void removePropertyChangeListener (String propertyName, PropertyChangeListener listener);	synchronized
}

Hierarchy: Object-->PropertyChangeSupport(Serializable)

Subclasses: javax.swing.event.SwingPropertyChangeSupport

Type Of: java.awt.Toolkit.desktopPropsSupport, java.beans.beancontext.BeanContextChildSupport.pcSupport

PropertyDescriptor

Java 1.1

java.beans

PJ1.1

A PropertyDescriptor object is a type of FeatureDescriptor that describes a single property of a JavaBeans component. The BeanInfo class for a bean optionally creates and initializes PropertyDescriptor objects to describe the properties the bean supports. Typically, only application builders and similar tools use the get and is methods to obtain this property description information.

You create a PropertyDescriptor by specifying the name of the property and the Class object for the bean. If you have not followed the standard design patterns for accessor-method naming, you can also specify the accessor methods for the property. Once a PropertyDescriptor is created, the setBound() and setConstrained() methods allow you to specify whether the property is bound and/or constrained. setPropertyEditorClass() allows you to specify a specific property editor that should edit the value of this property (this is useful, for example, when the property is an enumerated type with a specific list of supported values). The methods of the FeatureDescriptor superclass allow additional information about the property to be specified.

public class PropertyDescriptor extends FeatureDescriptor {
//	Public Constructors
	public PropertyDescriptor (String propertyName, Class beanClass) throws IntrospectionException;
	public PropertyDescriptor (String propertyName, java.lang.reflect.Method getter, java.lang.reflect.Method setter) throws IntrospectionException;
	public PropertyDescriptor (String propertyName, Class beanClass, String getterName, String setterName) throws IntrospectionException;
//	Property Accessor Methods (by property name)
	public boolean isBound ();
	public void setBound (boolean bound);
	public boolean isConstrained ();
	public void setConstrained (boolean constrained);
	public Class getPropertyEditorClass ();
	public void setPropertyEditorClass (Class propertyEditorClass);
	public Class getPropertyType ();
	public java.lang.reflect.Method getReadMethod ();
1.2	public void setReadMethod (java.lang.reflect.Method getter) throws IntrospectionException;
	public java.lang.reflect.Method getWriteMethod ();
1.2	public void setWriteMethod (java.lang.reflect.Method setter) throws IntrospectionException;
}

Hierarchy: Object-->FeatureDescriptor-->PropertyDescriptor

Subclasses: IndexedPropertyDescriptor

Returned By: BeanInfo.getPropertyDescriptors(), SimpleBeanInfo.getPropertyDescriptors()

PropertyEditor

Java 1.1

java.beans

PJ1.1

The PropertyEditor interface defines the methods that must be implemented by a JavaBeans property editor intended for use within an application builder or similar tool. PropertyEditor is a complex interface because it defines methods to support different ways of displaying property values to the user. It also defines methods to support different ways of allowing the user to edit the property value.

For a property of type x, the author of a bean typically implements a property editor of class xEditor. While the editor is implemented by the bean author, it is usually instantiated or used only by application builders or similar tools (or by a Customizer class for a bean). In addition to implementing the PropertyEditor interface, a property editor must have a constructor that expects no arguments, so that it can be easily be instantiated by an application builder. Also, it must accept registration and deregistration of PropertyChangeListener objects and send a PropertyChangeEvent to all registered listeners when it changes the value of the property being edited. The PropertyEditorSupport class is a trivial implementation of PropertyEditor, suitable for subclassing or for supporting a list of PropertyChangeListener objects.

public interface PropertyEditor {
//	Event Registration Methods (by event name)
	public abstract void addPropertyChangeListener (PropertyChangeListener listener);
	public abstract void removePropertyChangeListener (PropertyChangeListener listener);
//	Property Accessor Methods (by property name)
	public abstract String getAsText ();
	public abstract void setAsText (String text) throws IllegalArgumentException;
	public abstract java.awt.Component getCustomEditor ();
	public abstract String getJavaInitializationString ();
	public abstract boolean isPaintable ();
	public abstract String[ ] getTags ();
	public abstract Object getValue ();
	public abstract void setValue (Object value);
//	Public Instance Methods
	public abstract void paintValue (java.awt.Graphics gfx, java.awt.Rectangle box);
	public abstract boolean supportsCustomEditor ();
}

Implementations: PropertyEditorSupport

Returned By: PropertyEditorManager.findEditor()

PropertyEditorManager

Java 1.1

java.beans

PJ1.1

The PropertyEditorManager class is not meant to be instantiated; it defines static methods for registering and looking up PropertyEditor classes for a specified property type. A bean can specify a particular PropertyEditor class for a given property by specifying it in a PropertyDescriptor object for the property. If it does not do this, the PropertyEditorManager is used to register and look up editors. A bean or an application builder tool can call the registerEditor() method to register a PropertyEditor for properties of a specified type. Application builders and bean Customizer classes can call the findEditor() method to obtain a PropertyEditor for a given property type. If no editor has been registered for a given type, the PropertyEditorManager attempts to locate one. For a type x, it looks for a class xEditor first in the same package as x, and then in each package listed in the property editor search path.

public class PropertyEditorManager {
//	Public Constructors
	public PropertyEditorManager ();
//	Public Class Methods
	public static PropertyEditor findEditor (Class targetType);	synchronized
	public static String[ ] getEditorSearchPath ();	synchronized
	public static void registerEditor (Class targetType, Class editorClass);
	public static void setEditorSearchPath (String[ ] path);	synchronized
}

PropertyEditorSupport

Java 1.1

java.beans

PJ1.1

The PropertyEditorSupport class is a trivial implementation of the PropertyEditor interface. It provides no-op default implementations of most methods, so you can define simple PropertyEditor subclasses that override only a few required methods. In addition, PropertyEditorSupport defines working versions of addPropertyChangeListener() and removePropertyChangeListener(), along with a firePropertyChange() method that sends a PropertyChangeEvent to all registered listeners. PropertyEditor classes may choose to instantiate a PropertyEditorSupport object simply to handle the job of managing the list of listeners. When used in this way, the PropertyEditorSupport object should be instantiated with a source object specified, so that the source object can be used in the PropertyChangeEvent objects that are sent.

public class PropertyEditorSupport implements PropertyEditor {
//	Protected Constructors
	protected PropertyEditorSupport ();
	protected PropertyEditorSupport (Object source);
//	Event Registration Methods (by event name)
	public void addPropertyChangeListener (PropertyChangeListener listener);	Implements:PropertyEditor synchronized
	public void removePropertyChangeListener (PropertyChangeListener listener);	Implements:PropertyEditor synchronized
//	Public Instance Methods
	public void firePropertyChange ();
//	Methods Implementing PropertyEditor
	public void addPropertyChangeListener (PropertyChangeListener listener);	synchronized
	public String getAsText ();
	public java.awt.Component getCustomEditor ();	constant
	public String getJavaInitializationString ();
	public String[ ] getTags ();	constant
	public Object getValue ();
	public boolean isPaintable ();	constant
	public void paintValue (java.awt.Graphics gfx, java.awt.Rectangle box);	empty
	public void removePropertyChangeListener (PropertyChangeListener listener);	synchronized
	public void setAsText (String text) throws IllegalArgumentException;
	public void setValue (Object value);
	public boolean supportsCustomEditor ();	constant
}

Hierarchy: Object-->PropertyEditorSupport(PropertyEditor)

PropertyVetoException

Java 1.1

java.beans

serializable checked PJ1.1

Signals that a VetoableChangeListener that received a PropertyChangeEvent for a constrained property of a bean has vetoed that proposed change. When this exception is received, the property in question should revert to its original value, and any VetoableChangeListener objects that have already been notified of the property change must be renotified to indicate that the property has reverted to its old value. The VetoableChangeSupport class handles this renotification automatically and rethrows the PropertyVetoException to notify its caller that the change was rejected.

public class PropertyVetoException extends Exception {
//	Public Constructors
	public PropertyVetoException (String mess, PropertyChangeEvent evt);
//	Public Instance Methods
	public PropertyChangeEvent getPropertyChangeEvent ();
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->PropertyVetoException

Thrown By: VetoableChangeListener.vetoableChange(), VetoableChangeSupport.fireVetoableChange(), java.beans.beancontext.BeanContextChild.setBeanContext(), java.beans.beancontext.BeanContextChildSupport.{fireVetoableChange(), setBeanContext()}, java.beans.beancontext.BeanContextSupport.{setLocale(), vetoableChange()}, javax.swing.JComponent.fireVetoableChange(), javax.swing.JInternalFrame.{setClosed(), setIcon(), setMaximum(), setSelected()}

SimpleBeanInfo

Java 1.1

java.beans

PJ1.1

The SimpleBeanInfo class is a trivial implementation of the BeanInfo interface. The methods of this class all return null or -1, indicating that no bean information is available. To use this class, you need to override only the method or methods that return the particular type of bean information you want to provide. In addition, SimpleBeanInfo provides a convenience method, loadImage(), that takes a resource name as an argument and returns an Image object. This method is useful when defining the getIcon() method.

public class SimpleBeanInfo implements BeanInfo {
//	Public Constructors
	public SimpleBeanInfo ();
//	Public Instance Methods
	public java.awt.Image loadImage (String resourceName);
//	Methods Implementing BeanInfo
	public BeanInfo[ ] getAdditionalBeanInfo ();	constant default:null
	public BeanDescriptor getBeanDescriptor ();	constant default:null
	public int getDefaultEventIndex ();	constant default:-1
	public int getDefaultPropertyIndex ();	constant default:-1
	public EventSetDescriptor[ ] getEventSetDescriptors ();	constant default:null
	public java.awt.Image getIcon (int iconKind);	constant
	public MethodDescriptor[ ] getMethodDescriptors ();	constant default:null
	public PropertyDescriptor[ ] getPropertyDescriptors ();	constant default:null
}

Hierarchy: Object-->SimpleBeanInfo(BeanInfo)

VetoableChangeListener

Java 1.1

java.beans

event listener PJ1.1

This interface is an extension of java.util.EventListener. It defines the method a class must implement in order to be notified when a Java bean makes a change to a constrained property. A PropertyChangeEvent is passed to the VetoableChange() method when such a change occurs. If the VetoableChangeListener wants to prevent the change from occurring, this method should throw a PropertyVetoException.

public interface VetoableChangeListener extends java.util.EventListener {
//	Public Instance Methods
	public abstract void vetoableChange (PropertyChangeEvent evt) throws PropertyVetoException;
}

Hierarchy: (VetoableChangeListener(java.util.EventListener))

Implementations: java.beans.beancontext.BeanContextSupport

Passed To: VetoableChangeSupport.{addVetoableChangeListener(), removeVetoableChangeListener()}, java.beans.beancontext.BeanContextChild.{addVetoableChangeListener(), removeVetoableChangeListener()}, java.beans.beancontext.BeanContextChildSupport.{addVetoableChangeListener(), removeVetoableChangeListener()}, javax.swing.JComponent.{addVetoableChangeListener(), removeVetoableChangeListener()}

Returned By: java.beans.beancontext.BeanContextSupport.getChildVetoableChangeListener()

VetoableChangeSupport

Java 1.1

java.beans

serializable PJ1.1

VetoableChangeSupport is a convenience class that maintains a list of registered VetoableChangeListener objects and provides a fireVetoableChange() method for sending a PropertyChangeEvent to all registered listeners. If any of the registered listeners veto the proposed change, fireVetoableChange() sends out another PropertyChangeEvent notifying previously notified listeners that the property has reverted to its original value. Because of the extra complexity of correctly handling veto-able changes and because of some tricky thread-synchronization issues involved in maintaining the list of listeners, it is recommended that all Java beans that support constrained events create a VetoableChangeSupport object to which they can delegate the tasks of maintaining the list of listeners and of firing events.

public class VetoableChangeSupport implements Serializable {
//	Public Constructors
	public VetoableChangeSupport (Object sourceBean);
//	Event Registration Methods (by event name)
	public void addVetoableChangeListener (VetoableChangeListener listener);	synchronized
	public void removeVetoableChangeListener (VetoableChangeListener listener);	synchronized
//	Public Instance Methods
1.2	public void addVetoableChangeListener (String propertyName, VetoableChangeListener listener);	synchronized
1.2	public void fireVetoableChange (PropertyChangeEvent evt) throws PropertyVetoException;
1.2	public void fireVetoableChange (String propertyName, int oldValue, int newValue) throws PropertyVetoException;
1.2	public void fireVetoableChange (String propertyName, boolean oldValue, boolean newValue) throws PropertyVetoException;
	public void fireVetoableChange (String propertyName, Object oldValue, Object newValue) throws PropertyVetoException;
1.2	public boolean hasListeners (String propertyName);	synchronized
1.2	public void removeVetoableChangeListener (String propertyName, VetoableChangeListener listener);	synchronized
}

Hierarchy: Object-->VetoableChangeSupport(Serializable)

Type Of: java.beans.beancontext.BeanContextChildSupport.vcSupport

Visibility

Java 1.1

java.beans

PJ1.1

This interface is intended to be implemented by advanced beans that can run both with and without a GUI present. The methods it defines allow a bean to specify whether it requires a GUI and allow the environment to notify the bean whether a GUI is available. If a bean absolutely requires a GUI, it should return true from needsGui(). If a bean is running without a GUI, it should return true from avoidingGui(). If no GUI is available, the bean can be notified through a call to dontUseGui(), and if a GUI is available, the bean can be notified through a call to okToUseGui().

public interface Visibility {
//	Public Instance Methods
	public abstract boolean avoidingGui ();
	public abstract void dontUseGui ();
	public abstract boolean needsGui ();
	public abstract void okToUseGui ();
}

Implementations: java.beans.beancontext.BeanContext

Returned By: java.beans.beancontext.BeanContextSupport.getChildVisibility()

Chapter 9. The java.beans Package

Figure 9-1. The java.beans package