Mr. Happy Object teaches custom events

Learn custom events with a concrete example

By Tony Sintes, JavaWorld.com, 03/15/02

March 15, 2002

n "Events and Listeners," I outlined a generic recipe for creating and firing custom events. Since the original answer published, I've received several emails requesting a complete, concrete example.

In the original Java Q&A, I specified that you need three elements to generate and listen to custom events:

• An event class
• An event listener interface
• An event generator

Let's quickly review each.

Note: You can download this article's source code from Resources.

The event class

Any class can fit an event's role. At a minimum, an event should provide a method that allows the listener to retrieve the event's source.

Java includes a few built-in super types for creating events. Have a look at:

• Class EventObject
• Class AWTEvent

Normally you extend AWTEvent for events generated by a graphical component and EventObject any other time. If you do use one of these super types, you merely extend it and provide the methods unique to your custom event.

When creating an event class, you must guarantee that the event is immutable. The event generator will share the same event instance among the listeners; so ensure any one listener cannot change the event's state.

The listener interface

The listener interface provides the contract between the listeners and the event generator. The contract provides the event generator with the method to call when it fires an event.

When creating an event listener interface, you can add as many methods as you need. However, by convention, each method normally takes only one argument: the event.

The event generator

An event generator tracks listeners, provides a mechanism to add and remove listeners, and, at the appropriate time, fires events to the listeners.

When creating an event generator, make sure its registration mechanism is thread safe. Beyond that, writing an event generator class closely resembles writing any other class.

The concrete example

In this article, I bring back MrHappyObject first seen in "Client Callbacks."

Figure 1. Mr. Happy Object

In the original example, Mr. Happy Object became either happy, annoyed, or angry based on receiving hugs or pinches. In this example, we'll change how we learn about MrHappyObject's mood. Instead of calling a method, we'll register listeners with MrHappyObject. Whenever he changes his mood, MrHappyObject will send an event to his listeners.

Let's start by defining the new MoodEvent and some Mood constants.

The custom MoodEvent

MrHappyObject has three moods: happy, annoyed, and angry. When he fires an event, the listener will retrieve a mood. So, let's first define some mood constants:

public class Mood {
    public static final Mood HAPPY   = new Mood( "happy" );
    public static final Mood ANNOYED = new Mood( "annoyed" );
    public static final Mood ANGRY   = new Mood( "angry" );
    
    private String _mood;
    
    public String toString() {
        return _mood;
    }
    
    private Mood( String mood ) {
        _mood = mood;
    }
    
}

While we could have made do with some string constants, this approach is a little cleaner, in my opinion.