Book Home Java Enterprise in a Nutshell Search this book

Chapter 9. The java.beans Package

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

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.

AppletInitializerJava 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()

BeanDescriptorJava 1.1
java.beansPJ1.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()

BeanInfoJava 1.1
java.beansPJ1.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()

BeansJava 1.1
java.beansPJ1.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.2public static Object instantiate (ClassLoader cls, String beanName, java.beans.beancontext.BeanContext beanContext) throws java.io.IOExceptionClassNotFoundException;
1.2public 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;
}
CustomizerJava 1.1
java.beansPJ1.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);
}
DesignModeJava 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

EventSetDescriptorJava 1.1
java.beansPJ1.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()

FeatureDescriptorJava 1.1
java.beansPJ1.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.2public boolean isPreferred (); default:false
1.2public 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

IndexedPropertyDescriptorJava 1.1
java.beansPJ1.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.2public void setIndexedReadMethod (java.lang.reflect.Method getter) throws IntrospectionException;
1.2public void setIndexedWriteMethod (java.lang.reflect.Method setter) throws IntrospectionException;
}

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

IntrospectionExceptionJava 1.1
java.beansserializable 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.

IntrospectorJava 1.1
java.beansPJ1.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.2public static final int IGNORE_ALL_BEANINFO ; =3
1.2public static final int IGNORE_IMMEDIATE_BEANINFO ; =2
1.2public static final int USE_ALL_BEANINFO ; =1
// Public Class Methods
public static String decapitalize (String name);
1.2public static void flushCaches ();
1.2public static void flushFromCaches (Class clz);
public static BeanInfo getBeanInfo (Class beanClass) throws IntrospectionException;
1.2public 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
}
MethodDescriptorJava 1.1
java.beansPJ1.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()

ParameterDescriptorJava 1.1
java.beansPJ1.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()

PropertyChangeEventJava 1.1
java.beansserializable 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()

PropertyChangeListenerJava 1.1
java.beansevent 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()

PropertyChangeSupportJava 1.1
java.beansserializable 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.2public void addPropertyChangeListener (String propertyName, PropertyChangeListener listener); synchronized
1.2public void firePropertyChange (PropertyChangeEvent evt);
1.2public void firePropertyChange (String propertyName, int oldValue, int newValue);
1.2public void firePropertyChange (String propertyName, boolean oldValue, boolean newValue);
public void firePropertyChange (String propertyName, Object oldValue, Object newValue);
1.2public boolean hasListeners (String propertyName); synchronized
1.2public 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

PropertyDescriptorJava 1.1
java.beansPJ1.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.2public void setReadMethod (java.lang.reflect.Method getter) throws IntrospectionException;
public java.lang.reflect.Method getWriteMethod ();
1.2public void setWriteMethod (java.lang.reflect.Method setter) throws IntrospectionException;
}

Hierarchy: Object-->FeatureDescriptor-->PropertyDescriptor

Subclasses: IndexedPropertyDescriptor

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

PropertyEditorJava 1.1
java.beansPJ1.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()

PropertyEditorManagerJava 1.1
java.beansPJ1.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
}
PropertyEditorSupportJava 1.1
java.beansPJ1.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)

PropertyVetoExceptionJava 1.1
java.beansserializable 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()}

SimpleBeanInfoJava 1.1
java.beansPJ1.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)

VetoableChangeListenerJava 1.1
java.beansevent 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()

VetoableChangeSupportJava 1.1
java.beansserializable 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.2public void addVetoableChangeListener (String propertyName, VetoableChangeListener listener); synchronized
1.2public void fireVetoableChange (PropertyChangeEvent evt) throws PropertyVetoException;
1.2public void fireVetoableChange (String propertyName, int oldValue, int newValue) throws PropertyVetoException;
1.2public void fireVetoableChange (String propertyName, boolean oldValue, boolean newValue) throws PropertyVetoException;
public void fireVetoableChange (String propertyName, Object oldValue, Object newValue) throws PropertyVetoException;
1.2public boolean hasListeners (String propertyName); synchronized
1.2public void removeVetoableChangeListener (String propertyName, VetoableChangeListener listener); synchronized
}

Hierarchy: Object-->VetoableChangeSupport(Serializable)

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

VisibilityJava 1.1
java.beansPJ1.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()



Library Navigation Links

Copyright © 2001 O'Reilly & Associates. All rights reserved.