Events, listeners, and adapter classes

JavaBeans events are signalled when an activity occurs, such as a button being pressed or a window being closed. The visual editor for Java shows events in the Java Beans view, and you can use this view to add and remove events.

The list of defined events for a JavaBean is described in its BeanInfo class, which also controls the commonly used or preferred events.

You might want to add an event to a JavaBean if you want something to happen when the JavaBean is generated, such as a database update when a button is pushed. The Java Bean raising the event is the source, and the object that gets called back when the event is raised is known as the listener. Each JavaBean has an interface that allows it to notify the listeners for each event, as well as methods to add and remove listeners.

Typically, if the source JavaBean has a method XXX, there is a listener interface, XXXListener, and two methods. It is important that XXXListener extends java.util.EventListener. If it does not, and unless a specific BeanInfo is supplied, the event will not be discovered.

The methods on the XXXListener interface itself depend on the semantics of the event, but the convention is that their signature is void <eventOccurenceMethodName>(<EventStateObjectType> evt);. It is important that XXXListener extends java.util.EventObject. If it does not, and unless a specific BeanInfo is supplied, the event will not be discovered.

An example of an event is the JavaBean java.awt.Component, which raises events when the mouse moves over it. The listener interface, java.awt.event.MouseMotionListener, implements the following two methods:

To add a mouse listener, the java.awt.Component has the following two methods:

The second style of event is generated by a JavaBean when a property value changes. An example of this is the 'enabled' property on javax.swing.JButton. A property that fires an event when its value is changed is known as a bound property. Instead of having a separate listener interface for each bound property, there is a generic listener interface java.beans.PropertyChangeListener which has a single callback method void propertyCanged(PropertyChangeEvent evt); The argument PropertyChangeEvent has three methods that can be queried by the receiver of the method:

String getPropertyName() The name of the property that was changed on the JavaBean that caused the event to fire
Object getNewValue() The new value of the property
Object getOldValue() The value of the property before it was changed

To register interest in a JavaBean's property changes there are two methods: void addPropertyChangeListener(PropertyChangeListener listener); void addPropertyChangeListener(String propertyName, PropertyChangeListener listener);

The first of these methods is always present on a JavaBean that has bound properties. However, the second is optional and depends on the style of event registration used by author of the JavaBean. For example, AWT components use the first style of property change registration, while Swing components use both styles.

To use an event there are three objects:

  1. The JavaBean that raises the event ( the source )

  2. The class that receives notification from the source ( the listener )

  3. The class that implements the logic that occurs when the listener is called back.

Usually the last two are combined, so that the class that executes the logic either implements the listener interface directly or uses an inner class. The styles of code that the visual editor for Java recognizes and generates are covered in the section on Event Code Generation.

 

Adapter classes

Many listener interfaces have more than one callback method. An example is java.awt.FocusListener that has two methods; focusGained(java.awt.FocusEvent event) and focusLost(java.awt.FocusEvent event). When creating a listener class that implements the interface the Java compiler insists that all of the interface methods are implemented, which often results in many empty methods being created to satisfy its requirements when only one or some of its methods actually contain code. The following statement shows a FocusListener being used to perform some logic when a Java bean gains focus. However, an empty focusLost method must be provided.

javaBean.addFocusListener(new java.awt.event.FocusListener() {      
    public void focusGained(java.awt.event.FocusEvent e) {          
        doFocusGainedCode();      
     }          
        public void focusLost(java.awt.event.FocusEvent e) {      
     }  
});

To avoid having many empty listener methods for many listeners, Adapter classes are provided. These implement the listener interface, and provide empty no-op implementation of its methods. The advantage is that the listener can extend these, and only specialize methods of choice without having to provide default implementations for the rest ( these are inherited from the Adapter ).

javaBean.addFocusListener(new java.awt.event.FocusAdapter() {     
     public void focusGained(java.awt.event.FocusEvent e) {          
         doFocusGainedCode();      
         }  
   });

The visual editor is able to recognize and work with Adapter classes, and the section BeanInfo Events describes how you can associate adapter classes for your own events to the visual editor.

 

Parent topic

Handling events with the visual editor