[ Team LiB ] Previous Section Next Section

15.9 Manipulating Beans

The ShowBean class of Chapter 11 is a simple beanbox for displaying and experimenting with individual beans. The ShowBean code listed in Example 11-30 is concerned primarily with the creation of a GUI, and the key bean-manipulation methods are handled by a separate Bean class. Now that we've seen how to write a bean and its auxiliary classes, we're ready to tackle this Bean class itself; it is listed in Example 15-10.

An instance of the Bean class represents a single bean and its associated BeanInfo. Bean defines methods for querying and setting bean properties and for querying and invoking bean commands. (It defines a command as a method with no arguments and no return values.) In some ways, Bean can be considered a simplified interface to the BeanInfo class. Note that the java.beans package does not define any class named Bean: JavaBeans are not required to implement any Bean interface or extend any Bean superclass, so we've appropriated this class name for our own use here.

The Bean class has a public constructor that uses the java.beans.Introspector class to obtain BeanInfo for the bean object you pass to it. Bean also defines three static factory methods that you can use to instantiate the bean object instead of creating it yourself: forClassName( ) instantiates a named class to create the bean; fromSerializedStream( ) reads a serialized bean object from a java.io.ObjectInputStream (see Chapter 10); and fromPersistentStream( ) uses the JavaBeans persistence mechanism to read a bean instance from a stream using java.beans.XMLDecoder. XMLDecoder and the corresponding XMLEncoder class (demonstrated in Example 11-30) are new in Java 1.4 and are usually a better choice for saving the persistent state of beans: although the storage format is XML-based, it is usually more compact than the binary serialization format, and it is based on the public API of the bean rather than the private implementation, which is subject to versioning problems.

Pay attention to the ways Bean sets named properties. The setPropertyValue( ) method is passed a property name and value as strings. It checks whether the type of the named property is one that it knows how to convert a string to, and, if so, it converts the string and sets the property. If it does not know the type of the property, it attempts to find and use a PropertyEditor for that type, but this does not work for editors that implement getCustomEditor( ) instead of setAsText( ).

ShowBean uses setPropertyValue( ) to set property values specified on the command line. It does not use this method to set properties from its Properties menu, however; in this case, ShowBean calls getPropertyEditor( ). getPropertyEditor( ) does not return a PropertyEditor object directly—as we noted when implementing property editors, the PropertyEditor interface is confusing and hard to work with. Instead, getPropertyEditor( ) looks for a PropertyEditor for the named property and, if it finds one, returns a Component that is hooked up to the PropertyEditor. The Component is suitable for display in a dialog box or panel: when the user interacts with the returned component, the component interacts with the PropertyEditor to set the property.

Example 15-10. Bean.java
package je3.beans;
import java.awt.*;
import java.awt.event.*;
import javax.swing.*;
import javax.swing.event.*;
import java.beans.*;
import java.lang.reflect.*;
import java.util.*;
import java.util.List;  // explicit import to disambiguate from java.awt.List
import java.io.*;

 * This class encapsulates a bean object and its BeanInfo.
 * It is a key part of the ShowBean "beanbox" program, and demonstrates
 * how to instantiate and instrospect beans, and how to use reflection to 
 * set properties and invoke methods.  It also illustrates how to work with
 * PropertyEditor classes.
public class Bean {
    Object bean;     // The bean object we encapsulate
    BeanInfo info;   // Information about beans of that type
    Map properties;  // Map property names to PropertyDescriptor objects
    Map commands;    // Map command names to MethodDescriptor objects
    boolean expert;  // Whether to include "expert" properties and commands

    // Utility object used when invoking no-arg methods 
    static final Object[  ] NOARGS = new Object[0];

    // This constructor introspects the specified component.
    // Typically you'll use one of the static factory methods instead.
    public Bean(Object bean, boolean expert) throws IntrospectionException {
        this.bean = bean;     // The object to instrospect
        this.expert = expert; // Is the end-user an expert?

        // Introspect to get BeanInfo for the bean
        info = Introspector.getBeanInfo(bean.getClass( ));

        // Now create a map of property names to PropertyDescriptor objects
        properties = new HashMap( );
        PropertyDescriptor[  ] props = info.getPropertyDescriptors( );
        for(int i = 0; i < props.length; i++) {
            // Skip hidden properties, indexed properties, and expert 
            // properties unless the end-user is an expert.
            if (props[i].isHidden( )) continue;
            if (props[i] instanceof IndexedPropertyDescriptor) continue;
            if (!expert && props[i].isExpert( )) continue;
            properties.put(props[i].getDisplayName( ), props[i]);

        // Create a map of command names to MethodDescriptor objects
        // Commands are methods with no arguments and no return value.
        // We skip commands defined in Object, Component, Container, and
        // JComponent because they contain methods that meet this definition
        // but are not intended for end-users.
        commands = new HashMap( );
        MethodDescriptor[  ] methods = info.getMethodDescriptors( );
        for(int i = 0; i < methods.length; i++) {
            // Skip it if it is hidden or expert (unless user is expert)
            if (methods[i].isHidden( )) continue;
            if (!expert && methods[i].isExpert( )) continue;
            Method m = methods[i].getMethod( );
            // Skip it if it has arguments or a return value
            if (m.getParameterTypes( ).length > 0) continue;
            if (m.getReturnType( ) != Void.TYPE) continue;
            // Check the declaring class and skip useless superclasses
            Class c = m.getDeclaringClass( );
            if (c==JComponent.class || c==Component.class ||
                c==Container.class || c==Object.class)  continue;
            // Get the unqualifed classname to prefix method name with
            String classname = c.getName( );
            classname = classname.substring(classname.lastIndexOf('.')+1);
            // Otherwise, this is a valid command, so add it to the list
            commands.put(classname + "." + m.getName( ),  methods[i]);

    // Factory method to instantiate a bean from a named class
    public static Bean forClassName(String className, boolean expert)
        throws ClassNotFoundException, InstantiationException,
               IllegalAccessException, IntrospectionException
        // Load the named bean class
        Class c = Class.forName(className);
        // Instantiate it to create the component instance
        Object bean = c.newInstance( );

        return new Bean(bean, expert);

    // Factory method to read a serialized bean
    public static Bean fromSerializedStream(ObjectInputStream in,
                                            boolean expert)
        throws IOException, ClassNotFoundException, IntrospectionException
        return new Bean(in.readObject( ), expert);

    // Factory method to read a persistent XMLEncoded bean from a stream.
    public static Bean fromPersistentStream(InputStream in, boolean expert)
        throws IntrospectionException
        return new Bean(new XMLDecoder(in).readObject( ), expert);

    // Return the bean object itself.
    public Object getBean( ) { return bean; }

    // Return the name of the bean
    public String getDisplayName( ) {
        return info.getBeanDescriptor( ).getDisplayName( );

    // Return an icon for the bean
    public Image getIcon( ) {
        Image icon = info.getIcon(BeanInfo.ICON_COLOR_32x32);
        if (icon != null) return icon;
        else return info.getIcon(BeanInfo.ICON_COLOR_16x16);

    // Return a short description for the bean
    public String getShortDescription( ) {
        return info.getBeanDescriptor( ).getShortDescription( );

    // Return an alphabetized list of property names for the bean
    // Note the elegant use of the Collections Framework
    public List getPropertyNames( ) {
        // Make a List from a Set (from a Map), and sort it before returning.
        List names = new ArrayList(properties.keySet( )); 
        return names;

    // Return an alphabetized list of command names for the bean.
    public List getCommandNames( ) {
        List names = new ArrayList(commands.keySet( ));
        return names;

    // Get a description of a property; useful for tooltips
    public String getPropertyDescription(String name) {
        PropertyDescriptor p = (PropertyDescriptor) properties.get(name);
        if (p == null) throw new IllegalArgumentException(name);
        return p.getShortDescription( );

    // Get a description of a command; useful for tooltips
    public String getCommandDescription(String name) {
        MethodDescriptor m = (MethodDescriptor) commands.get(name);
        if (m == null) throw new IllegalArgumentException(name);
        return m.getShortDescription( );

    // Return true if the named property is read-only
    public boolean isReadOnly(String name) {
        PropertyDescriptor p = (PropertyDescriptor) properties.get(name);
        if (p == null) throw new IllegalArgumentException(name);
        return p.getWriteMethod( ) == null;

    // Invoke the named (no-arg) method of the bean
    public void invokeCommand(String name)
        throws IllegalAccessException, InvocationTargetException
        MethodDescriptor method = (MethodDescriptor) commands.get(name);
        if (method == null) throw new IllegalArgumentException(name);
        Method m = method.getMethod( );
        m.invoke(bean, NOARGS);

    // Return the value of the named property as a string
    // This method relies on the toString( ) method of the returned value.
    // A more robust implementation might use a PropertyEditor.
    public String getPropertyValue(String name)
        throws IllegalAccessException, InvocationTargetException
        PropertyDescriptor p = (PropertyDescriptor) properties.get(name);
        if (p == null) throw new IllegalArgumentException(name);
        Method m = p.getReadMethod( );           // property accessor method
        Object value = m.invoke(bean, NOARGS);  // invoke it to get value
        if (value == null) return "null";
        return value.toString( );                // use the toString method( )

    // Set the named property to the named value, if possible.
    // This method knows how to convert a handful of well-known types.  It
    // attempts to use a PropertyEditor for types it does not know about but
    // this only works for editors that have working setAsText( ) methods.
    public void setPropertyValue(String name, String value)
        throws IllegalAccessException, InvocationTargetException
        // Get the descriptor for the named property
        PropertyDescriptor p = (PropertyDescriptor) properties.get(name);
        if (p == null || isReadOnly(name))  // Make sure we can set it
            throw new IllegalArgumentException(name);

        Object v;  // Store the converted string value here.
        Class type = p.getPropertyType( );
        // Convert common types in well-known ways
        if (type == String.class) v = value;   
        else if (type == boolean.class) v = Boolean.valueOf(value);
        else if (type == byte.class) v = Byte.valueOf(value);
        else if (type == char.class) v = new Character(value.charAt(0));
        else if (type == short.class) v = Short.valueOf(value);
        else if (type == int.class) v = Integer.valueOf(value);
        else if (type == long.class) v = Long.valueOf(value);
        else if (type == float.class) v = Float.valueOf(value);
        else if (type == double.class) v = Double.valueOf(value);
        else if (type == Color.class) v = Color.decode(value);
        else if (type == Font.class) v = Font.decode(value);
        else {
            // Try to find a property editor for unknown types
            PropertyEditor editor = PropertyEditorManager.findEditor(type);
            if (editor != null) {
                v = editor.getValue( );
            // Otherwise, give up.
            else throw new UnsupportedOperationException("Can't set " +
                                                         "properties of type "+
                                                         type.getName( ));

        // Now get the Method object for the property setter method and
        // invoke it on the bean object, passing the converted value.
        Method setter = p.getWriteMethod( );  
        setter.invoke(bean, new Object[  ] { v });

    // Return a component that allows the user to edit the property value.
    // The component is live and changes the property value in real time;
    // there is no need to call setPropertyValue( ).
    public Component getPropertyEditor(final String name)
        throws IllegalAccessException, InvocationTargetException,
        // Get the descriptor for the named property; final for inner classes.
        final PropertyDescriptor p = (PropertyDescriptor) properties.get(name);
        if (p == null || isReadOnly(name))  // Make sure we can edit it.
            throw new IllegalArgumentException(name);

        // Find a PropertyEditor for the property
        final PropertyEditor editor;  // final for inner class use
        if (p.getPropertyEditorClass( ) != null) {  
            // If there is a custom editor for this property, instantiate one.
            editor = (PropertyEditor)p.getPropertyEditorClass( ).newInstance( );
        else {
            // Otherwise, look up an editor based on the property type
            Class type = p.getPropertyType( );
            editor = PropertyEditorManager.findEditor(type);
            // If there is no editor, give up
            if (editor == null) 
                throw new UnsupportedOperationException("Can't set " +
                                                        "properties of type " +
                                                        type.getName( ));

        // Get the property accessor methods for this property so we can
        // query the initial value and set the edited value
        final Method getter = p.getReadMethod( );
        final Method setter = p.getWriteMethod( );

        // Use Java reflection to find the current property value. Then tell
        // the property editor about it.
        Object currentValue = getter.invoke(bean, NOARGS);

        // If the PropertyEditor has a custom editor, then we'll just return
        // that custom editor component from this method. User changes to the
        // component change the value in the PropertyEditor, which generates
        // a PropertyChangeEvent. We register a listener so that these changes
        // set the property on the bean as well.
        if (editor.supportsCustomEditor( )) {
            final Component editComponent = editor.getCustomEditor( );
            // Note that we register the listener on the PropertyEditor, not
            // on its custom editor Component.
            editor.addPropertyChangeListener(new PropertyChangeListener( ) {
                    public void propertyChange(PropertyChangeEvent e) {
                        try {
                            // Pass edited value to property setter
                            Object editedValue = editor.getValue( );
                            setter.invoke(bean, new Object[  ] { editedValue});
                        catch(Exception ex) {
                                                  ex, ex.getClass( ).getName( ),
            return editComponent;

        // Otherwise, if the PropertyEditor is for an enumerated type based
        // on a fixed list of possible values, then return a JComboBox
        // component that allows the user to select one of the values.
        final String[  ] tags = editor.getTags( );
        if (tags != null) {
            // Create the component
            final JComboBox combobox = new JComboBox(tags);
            // Use the current value of the property as the currently selected
            // item in the combo box.
            combobox.setSelectedItem(editor.getAsText( ));
            // Add a listener to hook the combo box up to the property. When
            // the user selects an item, set the property value.
            combobox.addItemListener(new ItemListener( ) {
                    public void itemStateChanged(ItemEvent e) {
                        // Ignore deselect events
                        if (e.getStateChange( ) == ItemEvent.DESELECTED) return;
                        try {
                            // Get the user's selected string from combo box
                            String selectedTag =
                                (String)combobox.getSelectedItem( );
                            // Tell the editor about this string value
                            // Ask the editor to convert to the property type
                            Object editedValue = editor.getValue( );
                            // Pass this value to the property setter method
                            setter.invoke(bean, new Object[  ] { editedValue });
                        catch(Exception ex) {
                                                  ex, ex.getClass( ).getName( ),
            return combobox;

        // Otherwise, property type is not enumerated, and we use a JTextField
        // to allow the user to enter arbitrary text for conversion by the
        // setAsText( ) method of the PropertyEditor
        final JTextField textfield = new JTextField( );
        // Display the current value of the property in the field
        textfield.setText(editor.getAsText( ));
        // Hook the JTextField up to the PropertyEditor.
        textfield.addActionListener(new ActionListener( ) {
                // This is called when the user strikes the Enter key
                public void actionPerformed(ActionEvent e) {
                    try {
                        // Get the user's input from the text field
                        String newText = textfield.getText( );
                        // Tell the editor about it
                        // Ask the editor to convert to the property type
                        Object editedValue = editor.getValue( );
                        // Pass this value to the property setter method
                        setter.invoke(bean, new Object[  ] { editedValue });
                    catch(Exception ex) {
                                              ex, ex.getClass( ).getName( ),
        return textfield;
    [ Team LiB ] Previous Section Next Section