Design patterns for properties

I said earlier that tools like BeanBox found out about a Bean's properties by looking at its "get" and "set" methods. The easiest way to make properties visible is to follow these simple design patterns:

public propertyType getPropertyName()
public void setPropertyName( propertyType arg )
public boolean is PropertyName()

The last method is used only for properties with boolean values and is optional.

So it turns out that the appropriate "set" and "get" methods for these features of our Bean are already in the Dial class, either directly or inherited from java.awt.Component:

// Inherited from Component
public Color getForeground() 
public void setForeground(Color c) 

public Color getBackground() 
public void setBackground(Color c) 

public Font getFont()
public void setFont(Font f) 

public String getName()
public void setName(String name) 

// Part of the Dial itself
public int getValue()
public void setValue(int v)

public int getMinimum()
public void setMinimum(int m)

public int getMaximum()
public void setMaximum(int m)

One of the biggest changes between Versions 1.0 and 1.1 of Java was rewriting AWT in terms of these design patterns. For our Dial Bean, BeanBox uses the reflection API to find out about its methods (both its own and the methods it inherits); it then uses the design patterns to figure out what properties are available. When we use the properties sheet to change a value, the BeanBox dynamically invokes the correct "set" method to change the value.

But wait--if you look further at the Component class, you'll notice that other methods match the design pattern. For example, what about the setCursor() and getCursor() pair? Well, BeanBox doesn't know how to display or edit a cursor, so it simply ignores those properties in the properties sheet.

One more thought: BeanBox automatically pulls the property's name from the name of its accessor methods; it then "decapitalizes" the name for display on the properties sheet. For example, the "font" property is not listed as "Font". Later, I'll show how to provide a BeanInfo class that overrides the way these properties are displayed, letting you provide your own property names.

Finally, JavaBeans allows read-only and write-only properties, which are implemented by simply leaving out the "getter" or "setter" as desired.

A Bean for displaying text

One thing that we will need in almost any application is a plain old text label. Fortunately, the AWT's Label class gives us a head start. We'll package it up as a Bean as follows:

package magicbeans;

import java.awt.*;

public class TextLabel extends Label {

    public void setText( String s ) {
        super.setText( s );
        updateSize();
    }
    public void setFont( Font f ) {
        super.setFont( f );
        updateSize();
    }

    private void updateSize() {
        Container parent = getParent();
        if ( parent != null ) {
            invalidate();
            parent.validate();
        }
    }

    public void update( java.awt.Graphics g ) { }
}

Pretty much all of the contents of this class are refinements to make the TextLabel work a little more smoothly in a builder environment like BeanBox. Technically, we could have gotten by with a trivial subclass of Label, but it would have lacked the immediate feedback that we like when changing properties. In TextLabel, we override the two "set" methods that might change the preferred size of the Label: setText() and setFont(). Our new methods call our private updateSize() method to explicitly invalidate the Label and validate its parent container, causing it to lay out the Label again.[3] We have also overridden the AWT update() method, to prevent an accidental repaint() from messing up our component.[4]

[3] A proper implementation of Label should probably invalidate itself when its preferred size changes.

[4] Heavyweight AWT components like Label, Button, etc., do not expect to have an explicit update scheduled via repaint(). As you'll recall, the default implementation of update() wipes the area to the background color, whether or not the component has a peer. For a lightweight component, this behavior is undesirable.

Go ahead, repackage and try out the label in the BeanBox. Don't forget to add TextLabel.class to the manifest and to specify that it is a Bean. Once you have the TextLabel in the BeanBox, it should automatically grow to accommodate changes in text and font. Notice the property called "alignment" (which it inherited from the AWT Label class); try changing its value to 1, 2, or 3, and see what happens.

A Bean for validating numeric data

Another component that we're sure to need in a form is a text field that accepts numeric data. Let's build a text entry Bean that accepts and validates numbers and makes the values available as a property. You should recognize almost all of the parts of the NumericField Bean:

package magicbeans;

import java.awt.*;
import java.awt.event.ActionEvent;
import java.beans.*;

public class NumericField extends TextField {
    private double value;
    private PropertyChangeSupport propChanges = new PropertyChangeSupport(this);

    public NumericField() {
        enableEvents( AWTEvent.ACTION_EVENT_MASK );
    }
 
    public void processActionEvent(ActionEvent e) {
        try { 
            setValue( new Double( getText() ).doubleValue() );
        } catch ( NumberFormatException ex ) { 
            select(0, getText().length());
        }
        super.processActionEvent(e);
    }

    public double getValue() {
        return value;
    }
    public void setValue( double newValue ) {
        double oldValue = value;
        setText( "" + newValue );
        propChanges.firePropertyChange("value", 
            new Double(oldValue), new Double(newValue));
    }

    public void setColumns( int cols ) {
        super.setColumns( cols );
        Container parent = getParent();
        if ( parent != null ) {
            invalidate();
            parent.validate();
        }
    }

    public void addPropertyChangeListener(PropertyChangeListener listener) {
        propChanges.addPropertyChangeListener(listener);
    }
    public void removePropertyChangeListener(PropertyChangeListener listener) {
        propChanges.removePropertyChangeListener(listener);
    }

    public void update( Graphics g ) { } 
}

NumericField extends the AWT's TextField component; it's fairly similar to our TextLabel. The heart of NumericField is in the processActionEvent() method. You'll recall that a TextField generates ActionEvents whenever the user presses Return to enter the data. We catch those events and try to parse the user's entry as a number, giving it a Double value. If we succeed, we update the "value" property using our setValue() method. setValue() then fires a PropertyChangeEvent to notify any interested Beans. This means that NumericField lets us bind its "value" property. If the text doesn't parse properly as a number, we give feedback to the user by selecting (highlighting) the text.

As with our TextLabel, we override a method that might affect the NumericField's size--setColumns()--and add code to validate our container whenever the number of columns changes. You should be able to change the "columns" property of the NumericField and to adjust its size dynamically. (We'll let you paste in the bit of code to handle setFont() if you want.)

Verify the operation of NumericField by placing two of them in the BeanBox and binding the "value" property of one to the other. You should be able to enter a new floating point value and see the change reflected in the other.

An invisible multiplier

Finally, let's try our hand at an invisible Bean: one that performs a calculation rather than providing part of a user interface. Multiplier is a simple invisible Bean that multiplies the values of two of its properties (A and B) to produce the value of a third read-only property (C). Here's the code:

package magicbeans;

import java.beans.*;

public class Multiplier implements java.io.Serializable {
    private double a, b, c;
    
    synchronized public void setA( double val ) { 
        a = val; 
        multiply();
    }
    synchronized public double getA() { 
        return a; 
    }
    synchronized public void setB( double val ) { 
        b = val; 
        multiply();
    }
    synchronized public double getB() { 
        return b; 
    }
    synchronized public double getC() { 
        return c; 
    }   
    private void multiply() {
        double oldC = c;
        c = a * b;
        propChanges.firePropertyChange("c", new Double(oldC), new Double(c));
    }

    private PropertyChangeSupport propChanges = new PropertyChangeSupport(this);

    public void addPropertyChangeListener(PropertyChangeListener listener) {
        propChanges.addPropertyChangeListener(listener);
    }
    public void removePropertyChangeListener(PropertyChangeListener listener) {
        propChanges.removePropertyChangeListener(listener);
    }
}

The code is straightforward. Whenever the value of property A or B changes, we call multiply(), which multiplies their values and fires a PropertyChangeEvent. So Multiplier supports binding of any of its properties.

Putting them together

Finally, let's demonstrate that we can put our Beans together in a useful way. Arrange three TextLabels, three NumericFields, and a Multiplier into the scene in Figure 18.9.

Figure 18.9: TextLabels, NumericFields, and a Multiplier

Bind the values of the first two NumericFields to the A and B properties of the Multiplier; bind the C value to the third NumericField. Now we have a simple calculator. You could use this as a tip calculator, but it's important to realize that much more is possible. Try some other arrangements. Can you build a calculator that squares a number? Can you see how you might build a simple spreadsheet?

Before moving on, save this work so that you can reuse it later. This time, use the BeanBox's Serialize component option to serialize the BeanBox container itself. To select the top-level BeanBox, click on the background of the workspace. The dashed line should appear around the entire BeanBox. Then use the Serialize component option to save your work. By serializing the BeanBox container, we save all of the Beans it contains and all of their interconnections. In a section later in this chapter, we'll show you how to put these to use.

Properties info

We'll start out by describing the Dial's properties. To do so, we must implement the getPropertyDescriptors() method. This method simply returns an array of PropertyDescriptor objects--one for every property we want the development tool to know about.

To create a PropertyDescriptor, we call its constructor with two arguments: the property's name and the class. In the following code, we create descriptors for the Dial's "value," "minimum," and "maximum" properties. Then we call a few methods of the PropertyDescriptor class to provide additional information about each property. In this example, we call the setBound() method to state that "minimum" and "maximum" are not bound properties but that "value" is a bound property. Our code also is prepared to catch an IntrospectionException, which can occur if something goes wrong while creating the property descriptors.

package magicbeans;

import java.beans.*;

public class DialBeanInfo extends SimpleBeanInfo {

    public PropertyDescriptor[] getPropertyDescriptors() {
        try {
            PropertyDescriptor value = 
                new PropertyDescriptor("value", Dial.class);
            PropertyDescriptor minimum = 
                new PropertyDescriptor("minimum", Dial.class);
            PropertyDescriptor maximum = 
                new PropertyDescriptor("maximum", Dial.class);
            
            value.setBound(true);
            minimum.setBound(false);
            maximum.setBound(false);

            return new PropertyDescriptor [] { value, minimum, maximum };
        } catch (IntrospectionException e) {
            return null; 
        }
    }

Perhaps the most interesting thing about DialBeanInfo is that, by providing explicit information for our properties, we automatically hide any other properties that introspection might find. In other words, if you don't provide any property information, a development tool like BeanBox will find out about all sorts of properties, including properties inherited from the superclass: when we loaded the Dial into the BeanBox, we saw a number of properties inherited from Component. If you compile DialBeanInfo, package it with the Dial, and load the resulting JAR file into the BeanBox, you'll see that the Component properties no longer appear in the properties sheet.

Of course, a PropertyDescriptor can provide a lot of other information about a property: it can provide the names of the accessor methods, if you decide not to use the design patterns; whether the property is constrained; and a class to use as a property editor, if the standard property editors aren't sufficient.

Events info

The Dial defines its own event: the DialEvent. We'd like to tell development tools about this event, so that we can build applications using it. The process for telling the world about our event is similar to what we did previously: we add a method to the DialBeanInfo class called getEventSetDescriptors(), which returns an array of EventSetDescriptors.

There's just one minor complication: events are described in terms of their listener interfaces, not in terms of the event classes themselves. So our getEventSetDescriptors() method creates a descriptor for the DialListener interface. We also have to tell the world that we generate PropertyChangeEvents, so we create a descriptor for the PropertyChangeListener. Here's the code to add to the DialBeanInfo class:

public class DialBeanInfo extends SimpleBeanInfo {
	...

    public EventSetDescriptor[] getEventSetDescriptors() {
        try {
            EventSetDescriptor dial = new EventSetDescriptor( Dial.class, 
                "dialAdjusted", DialListener.class, "dialAdjusted");
            dial.setDisplayName("Dial Adjusted");

            EventSetDescriptor changed = new EventSetDescriptor( Dial.class,
                "propertyChange", PropertyChangeListener.class, 
                "propertyChange" );
            changed.setDisplayName("Bound property change");
    
            return new EventSetDescriptor [] { dial, changed };
        } catch (IntrospectionException e) {
            return null; 
        }
    }

In this method, we create two EventSetDescriptor objects: dial and changed. The constructor for an EventSetDescriptor takes four arguments: the class that generates the event, the name of the event set (i.e., the name that will be displayed by default by a development tool), the listener class, and the name of the method to which the event can be delivered. (Other constructors let you deal with listener interfaces that have several methods.) After creating these objects, we call the setDisplayName() method to provide a more friendly name to be displayed by development tools like the BeanBox.

Just as the property descriptors we supply hid the properties that were discovered by reflection, the EventSetDescriptors hide events that are inherited from the Component class. Therefore, when you recompile DialBeanInfo, package it in a JAR, and load it into the BeanBox, you'll no longer see mouse events, action events, and all the other AWT events. You will see only the two events that we have explicitly described: our own DialEvent and a PropertyChangeEvent.

Again, once you have an EventSetDescriptor, you can provide other kinds of information about the event. In particular, you can state that the event is "unicast," which means that it can only have one listener.

Supplying icons

Some of the Beans that come with the BeanBox are displayed on the palette with a cute icon. This makes it easier for a nontechnical user to identify which Bean he or she wants. Icon images are supplied using the BeanInfo object we have been developing. To supply an icon, implement the getIcon() method. You may supply as many as four icons: they may be either 16 x 16 or 32 x 32, and either color or monochrome. Here's the getIcon() method for DialBeanInfo:

public class DialBeanInfo extends SimpleBeanInfo {
	...

    public java.awt.Image getIcon(int iconKind) {

        if (iconKind == BeanInfo.ICON_COLOR_16x16) {
            return loadImage("DialIconColor16.gif");
        } else
        if (iconKind == BeanInfo.ICON_COLOR_32x32) {
            return loadImage("DialIconColor32.gif");
        } else
        if (iconKind == BeanInfo.ICON_MONO_16x16) {
            return loadImage("DialIconMono16.gif");
        } else
        if (iconKind == BeanInfo.ICON_MONO_32x32) {
            return loadImage("DialIconMono32.gif");
        }
        return null;
    }

This method is called with a constant indicating what kind of icon is being requested; for example, BeanInfo.ICON_COLOR_16x16 requests a 16 x 16 color image. If an appropriate icon is available, it loads the image and returns an Image object. If the icon isn't available, it returns null. For convenience, you can package the images in the same JAR file as the Bean and its BeanInfo class.

While we haven't used them, you can also use a BeanInfo object to provide information about other public methods of your Bean, "indexed properties" (i.e., array-valued properties), and other features.

Creating customizers and property editors

JavaBeans also lets you provide a customizer for your Beans. Customizers are objects that do advanced customization for a Bean as a whole; they let you provide your own GUI for tweaking your Bean. (The Select Bean uses a customizer rather than the standard properties sheet.) I won't show you how to write a customizer; it's not too difficult, but it's beyond the scope of this chapter. Suffice it to say that a customizer must implement the java.beans.Customizer interface, and should extend Component so that it can be displayed.

A property editor isn't quite as fancy as a customizer. Property editors are a way of giving the properties sheet additional capabilities. For example, you would supply a property editor to let you edit a property type that is specific to your Bean. You could provide a property editor that would let you edit an object's price in dollars and cents. We've already seen a couple of property editors: the editor used for Color-valued properties is fundamentally no different from a property editor you might write yourself. In addition, the Molecule Bean used a property editor to specify its moleculeName property.

Again, describing how to write a property editor is beyond the scope of this chapter. Briefly, a property editor must implement the PropertyEditor interface; it usually does so by extending the PropertyEditorSupport class, which provides default implementations for most of the methods.