Featured White Papers

• Measuring Risk to Improve Java Software Quality
• Do You Really Get Classloaders?
• Pragmatic Continuous Delivery with Jenkins, Nexus, and LiveRebel
• Your Next Java Web App: Less XML, No Long Restarts, Fewer Hassles
• Coding with JRebel, Java Forever Changed
• 2012 Developer Productivity Report: Java Tools, Tech, Devs, and Data

Sponsored Links

• Graph databases are 1000x faster than relational.

  Learn More!

• Career opportunities at Harman- Careers That'll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

The 'event generator' idiom

How and when to make a Java class observable

By Bill Venners, JavaWorld.com, 09/01/98

Page 4 of 5

// In file eventgui/ex1/AnsweringMachine.java
public class AnsweringMachine
    implements TelephoneListener {
    public void telephoneRang(TelephoneEvent e) {
        System.out.println("AM hears the phone ringing.");
    }
    public void telephoneAnswered(TelephoneEvent e) {
        System.out.println("AM sees that the phone was answered.");
    }
}
// In file eventgui/ex1/Person.java
public class Person {
    public void listenToPhone(Telephone t) {
        t.addTelephoneListener(
            new TelephoneAdapter() {
                public void telephoneRang(TelephoneEvent e) {
                    System.out.println("I'll get it!");
                }
            }
        );
    }
}

Note that AnsweringMachine implements the TelephoneListener interface directly. By contrast, the Person object instantiates an anonymous inner class that subclasses the TelephoneAdapter class. This anonymous inner class overrides the only method of interest to the Person object: telephoneRang().

The last class we need to define is an example application that will exercise all these classes and interfaces:

// In file eventgui/ex1/Example1.java
public class Example1 {
    public static void main(String[] args) { 
        Telephone ph = new Telephone();
        Person bob = new Person();
        AnsweringMachine am = new AnsweringMachine();
        ph.addTelephoneListener(am);
        bob.listenToPhone(ph);
        ph.ringPhone();
        ph.answerPhone();
    }
}

When executed, the Example1 application prints out:

The answering machine hears the phone ringing.
I'll get it!
The answering machine sees that the phone was answered.

Implementation guidelines
With the guidelines I list in this section, I am trying to define a default way to implement this idiom. I say default because, unless you have a specific reason to take a different implementation approach, you should automatically use the approach recommended in these guidelines. My theory is that if you adhere closely to the default implementation approach, it will be easier for your fellow programmers to recognize the idiom in your work. More importantly, I feel that such idiom recognition will make it easier for your fellow programmers to understand, use, and change your code.

On the other hand, you should feel free to depart from the default approach to implementing the idiom when you feel it makes sense. In fact, I myself describe two potential "variants" to the default approach in the next section.

Now, on to the guidelines:

1. Create just one event object for each "firing" and pass it to all listeners.
   
   
2. Make the event object immutable, so there is no possibility that a listener will change the event object as it propagates.
   
   
3. Use a single thread to notify all listeners. In other words, the fire method should go through the list of listeners and invoke the appropriate handler method upon one listener after the other.
   
   
4. Take a snapshot (clone the list) of registered listeners at the beginning of the firing process, then send the event to each listener registered at the time the snapshot was taken.
   
   
5. Keep event handlers (listener methods) short. These methods should execute quickly because (in the default approach) listeners are notified one at a time. In other words, listeners must wait until all listeners before them in the queue have been notified, so it is good citizenship for listeners to be quick about handling events. If an event handler method really needs to do considerable work as a result of an event notification, consider designing the handler such that it fires off or notifies another thread that does the actual time-consuming work.
   
   
6. Don't write listeners such that they depend on an order of notification.
   
   
7. If a listener is not interested in all events that compose a particular event category, consider subclassing an adapter class and just overriding the methods of interest.

Variants
The following are variants to the default approach to implementing idioms: