Introduction to !EventDispatcher

The easiest way to explain, how !EventDispatcher works is to start off with a very simple example.

Implementing an event listener

Event listeners need to implement the interface net.schst.!EventDispatcher.!EventListener, which only requires one method to be implemented, handleEvent(Event e).

Here's a simple example of an event listener, that sends some debug information to STDOUT:

import net.schst.EventDispatcher.EventListener;

public class DebugHandler implements EventListener {

    /**
     * Handle the event
     */
    public void handleEvent(Event e) {
        System.out.println("Event has been triggered.");
        System.out.println("Event-name    : " + e.getName());
        System.out.println("Event-context : " + e.getContext());
        System.out.println("in queue      : " + e.isQueued());
        System.out.println();
    }
}

When this listener receives an event, it only displays the name of the event, the context of the event and information, whether this event has been queued. You'll learn more about the [wiki:DocsEventQueue The event queue] later.

Registering an event listener

Registering this listener for an event is extremely easy. At first you need to aquire an instance of event dispatcher, which can be done using the static getInstance() method.

Then you create a new instance of the !DebugHandler you just implemented and pass it to the addListener method of !EventDispatcher. This method requires two parameters to be set:

• name of the event for which you want to register the listener

• the listener instance

  import net.schst.EventDispatcher.*;

  EventListener listener = new DebugHandler(); EventDispatcher disp = EventDispatcher.getInstance(); disp.addListener("onLogin", listener);

Triggering an event

In a probably totally different part of your application you'll now want to signal, that somebody sucessfully completed a login to your application.

This is also very easy to do, you only need to follow these two steps:

1. Aquire the same !EventDispatcher instance as before, using getInstance()
2. Trigger a new event on the dispatcher instance

To trigger an event you call the triggerEvent() method and pass in the name of the event as the first parameter to the method. The second parameter defines, whether you want the event to be queued (again, more about queueing later) and the third paramter is the context of the event.

In the case of a user, that authenticated, you probably want to pass an object that contains information about this user.

import net.schst.EventDispatcher.*;

EventDispatcher disp = EventDispatcher.getInstance();
Event e = (Event)disp.triggerEvent("onLogin", true, new User());

The triggerEvent() method has various signature, e.g. you can call it with an additional user info parameter or leave out the event context if there is none.

The triggerEvent() method will return the created Event object, which contains the the context and user info if you passed them to triggerEvent().

In most cases you will probably discard the return value, unless you do allow the event listeners to cancel the event or event modify the event context.