Documentation | JavaBeans | Interface

Bean Interface

Spin interacts with JavaBeans through properties, events, and methods.

Properties

A bean's visual and behavioral attributes are stored as properties. A property is a value in the bean that can be queried and set via a standard interface.

Implementing a Property

A property is implemented as a pair of methods: a get-method and a set-method. These methods manipulate the property's value and must have signatures that follow the following pattern:

public TYPE getNAME()
public void setNAME(TYPE value)

"NAME" is the name of the property and "TYPE" is its type. The set-method must take exactly one argument whose type must match the return type of the get-method. This type can be any valid Java type.

In addition, boolean properties may be defined using an alternate get-method signature:

public boolean isNAME()
public void setNAME(boolean value)

Properties often correspond to specific instance variables within the bean, but this is not strictly necessary. As long as the accessor methods have the correct signatures, the name will be visible as a property.

Examples of Properties

The Juggler JavaBean has a property called AnimationRate whose value is an integer. This is implemented by the Juggler bean as two methods:

public int getAnimationRate().
public void setAnimationRate(int size)

Similarly, if you are creating a bean and you want to define a property called Size whose value is a java.awt.Dimension, you must implement the following two methods:

public java.awt.Dimension getSize() {...}
public void setSize(java.awt.Dimension newsize) {...}

Events

Events are the means by which a bean tells other beans that something has happened. A common use for events is to respond to user input events, such as clicking on a visible bean with the mouse or pressing a key on the keyboard.

A bean that produces events is called an event source. A bean indicates its interest in an event by registering an event listener with the event source. Then, when the event occurs, the the event source sends the event to every bean that has expressed interest. This is analogous to how you might subscribe to a magazine by sending a subscription request to the publisher. When the magazine is printed, the publisher sends a copy to every subscriber.

1. Listener Registration

The bean must implement a pair of methods for registering and removing "Listeners" that wish to receive a specific kind of event. These methods must be signed:

public void addXListener(XListener listener)
public void removeXListener(XListener listener)

where "X" is the name of the event. For example, the MyLine bean generates "LineClick" events whenever the mouse is clicked on its line. The listener registration methods for this event are:

public void addLineClickListener(LineClickListener clickListener)
public void removeLineClickListener(LineClickListener clickListener)

2. The Listener Interface

The interface passed in listener registration is called the "Listener Interface." This interface defines notification methods that are selectively called by the bean when an event occurs.

The listener interface must be public, and it must extend java.util.EventListener (see LineClickListener.java):

public interface LineClickListener extends java.util.EventListener {
    public void lineClicked( LineClickEvent e );
}

The interface may define as many notification methods as needed. Each method must take exactly one event object, as described below.

3. The Event Object

The event objects that are passed to the listener interface methods must extend java.util.EventObject (see LineClickEvent.java):

public class LineClickedEvent extends java.util.EventObject

The methods implemented by the event object should be "get" or "is" methods (like property get-methods) that provide information about the event.

Methods

Methods are the means by which you define what your bean can do. Any public instance method implemented by a bean that is not Event- or Property-related is (by default) a Bean method.

Bean methods should be named to convey their function, because their names appear in Spin and other tools.

Here is a message signature we could add to the MyLine example bean to translate it by a specified x and y amount:

public void translateBy(java.awt.Point vector)

The translateBy method adds the vector specified to the bean's Point_A and Point_B properties, effectively translating the line displayed by the bean.

A message may also return a result if desired.

Important Note

To make a Bean method useful, arguments passed to it and values returned by it should be other beans, primitive types, or standard Java types (such as Color, String). The same thing is true of properties, and data passed in an event. You should not use instances of arbitrary Java classes.

This is a significant way in which programming components differs from regular object-oriented programming. When programming JavaBeans, the user will be directly manipulating the information that is passed between beans, so they should be recognizable entities, and it should be possible for the user to view and edit them.