Home

Welcome to your wiki!

This is the default page, edit it as you see fit. To add a page simply reference it within brackets, e.g.: [SamplePage].

The wiki uses Markdown syntax.

[Jose Heitor]

Introduction

This document describes the key elements to using the Java Events Framework (JEF). The sample code snippets are extracted from the source code of the Sample application which is available for download from the Downloads page of this project.




Any instantiatable class can use the Java Events Framework to become and Event-Handler or Event-Dispatcher object. A class can also be both; providing a two way communication pipe with other objects from the same or other classes. In any of these cases, the classes must import the JEF package with this statement:

import com.heitorprojects.event.*;

Event Listeners

To 'handle' event notifications a class must declare that it implements the IEventHandler interface provided in the JEF package.

public class JEFMouseSample implements IEventHandler

It must then supply the logic implementation for one single method:

public void handleEvent(IEventSource source, String event, Object params)
{
  // Implementation logic to handle event notifications goes here...
}

But before it can receive notifications, it must 'register' itself with the object that is generating the events. This is simply accomplished by calling the following method on the event dispatching object:

// Instantiate an object of the class that will generate some events ...
mp = new MousePointer("MousePointer.Genius");

// Register this object to receive both MOVE and CLICK event notifications.
mp.addEventHandler(this, MousePointer.EventTypes.MOUSE_MOVE.toString());
mp.addEventHandler(this, MousePointer.EventTypes.MOUSE_CLICK.toString());

If at any stage of execution it no longer needs to receive one or more of the events that this object dispatches, it can call the following method to de-register itself from receiving notifications for the specific event(s):

// De-register this object's event handlers so it will no longer be notified of events
mp.removeEventHandler(this, MousePointer.EventTypes.MOUSE_MOVE.toString());
mp.removeEventHandler(this, MousePointer.EventTypes.MOUSE_CLICK.toString());

Event Dispatchers

To 'dispatch' event notifications a class must declare that it implements the IEventSource interface provided in the JEF package.

public class MousePointer implements IEventSource

It must then supply the logic implementation for two methods that have been discussed above which are called from objects that wish to receive event notifications (event handlers):

public void addEventHandler(IEventHandler target, String event)
{
  // Implementation logic goes here...
}

The above method is called by 'listeners' who wish to be notified of one or more events that this dispatcher class generates and the method below is called by the same objects to 'de-register' themselves from receiving further notifications of one or more events from this object:

public void removeEventHandler(IEventHandler target, String event)
{
  // Implementation logic goes here...
}

An additional method which must also be implemented by the class dispatching events is the following method, which provides a quick and easy way for 'listener' objects that receive event notifications to obtain a unique name to identify the source object that dispatched the event. It is up to the developer that creates objects of the event-dispatching class, to provide a unique String name for each of the objects that he instantiates, at object creation time.

public String getId()
{
  return id;
}

In addition to implementing the above methods from the IEventSource interface, a class that generates events must instantiate a single object of the EventsManager class.

private final EventsManager ev;

This is the class that exposes the necessary methods required to dispatch events. It encapsulates all the 'plumbing' that manages the registration, de-registration and dispatching of events to registered 'listeners'.


At initialization, an array of Event objects is passed to its constructor, each of which encloses the various settings that define the name and threading model / priority (see the included Javadoc documentation for specific details of the available settings) for each type of event that this event-dispatching class generates.

Event[] events = new Event[2];
events[0] = new Event(EventTypes.MOUSE_CLICK.toString(), 5, true);
events[1] = new Event(EventTypes.MOUSE_MOVE.toString(), 3);
ev = new EventsManager(this, events);

When an event needs to be dispatched, the object calls the following method on its EventsManager object to manage the dispatching of the event to all registered 'listener' objects.

ev.raiseEvent("SOME_EVENT_NAME");

Optionally it can deliver one or more parameters to the event listeners through its optional params method parameter. If multiple objects need to be passed, they can be encapsulated in an Array, Collection or a custom class, as the params parameter is conveniently defined as type Object.

// Package the relevant parameters for this event conveniently in a new Hashtable instance.
params = new Hashtable<String, Object>();
params.put("mouseX", (Integer)x);
params.put("mouseY", (Integer)y);
params.put("mouseButton", (String)but.toString());

// Call the EventsManager to dispatch this event to all registered listeners, passing the
// Hashtable containing the associated parameters of this event.
ev.raiseEvent(EventTypes.MOUSE_CLICK.toString(), params);

See the Javadoc documentation supplied with the framework's source to obtain specific details of method declarations and variable types.