org.exolab.jms.events
Interface EventManager

All Superinterfaces:

java.io.Serializable, org.exolab.core.service.Serviceable

All Known Implementing Classes:

BasicEventManager

public interface EventManager

extends org.exolab.core.service.Serviceable

The EventManager manages Event objects. It has methods to register and unregister events. It also extends Runnable interface which defines the thread responsible for dispatching events.

An event is defined to occur at sometime in the future, as specified either by an absolute time through registerEvent(org.exolab.jms.events.Event, long) or as relative time through registerEventRelative(org.exolab.jms.events.Event, long). An event must have an associated event type and may have an attached Serializable object, which is used when the EventManager makes a callback to the registered handler when the event fires.

The register methids will return an event identifier which can subsequently be used to unregister the event through the unregisterEvent(java.lang.String) event. This is the only means of unregister an event.

If the Event object is incorrectly specified then the IllegalEventDefinedException exception is raised.

When an event fires the EventManager is responsible for ensuring that the event handler is notified. If the event handler has since been removed then the EventManager must gracefully abort the delivery and continue processing the next event.

Objects of type Event need to survive subsequent EventManager restarts, as such they must be persisted, which implies that the EventHandler needs to also be persisted. The ability to store the EventHandler as a HandleIfc object which can later be resolved to an object will be required.

This class is also Serviceable, which implies that it can be added and controlled by a ServiceManager.

Version:

$Revision: 1.3 $ $Date: 2003/08/17 01:32:22 $

Author:

Jim Alateras

Method Summary

java.lang.String	registerEvent(Event event, long absolute) Register an event to be fired once and only once at the specified abolsute time.
java.lang.String	registerEventRelative(Event event, long relative) Register an event to be fired once and only once at a time relative to now.
void	unregisterEvent(java.lang.String id) Unregister the event specified by the event identifier.

Methods inherited from interface org.exolab.core.service.Serviceable

getName, getState, restart, start, stop

Method Detail

registerEvent

public java.lang.String registerEvent(Event event,
                                      long absolute)
                               throws IllegalEventDefinedException

Register an event to be fired once and only once at the specified abolsute time. The event object must be Serializable so that it can be persisted and restored across EventManager restarts.

If the specified event is ill-defined then the IllegalEventDefined- Exception exception is thrown.

Similarly, if the abolsute time has already passed then the exception IllegalEventDefinedException is raised.

The method returns an unique event identifier, which can subsequently be used to deregister the event.

Parameters:

event - information about the event

abolsute - the abolsute time, in ms, that the event must fire

Returns:

String unique event identifier

Throws:

IllegalEventDefinedException -

registerEventRelative

public java.lang.String registerEventRelative(Event event,
                                              long relative)
                                       throws IllegalEventDefinedException

Register an event to be fired once and only once at a time relative to now. The event object must be Serializable so that it can be persisted and restored across EventManager restarts.

If the specified event is ill-defined then the IllegalEventDefined- Exception exception is thrown.

The method returns an unique event identifier, which can subsequently be used to deregister the event.

Parameters:

event - information about the event

relative - the relative time in ms (currently no reference to locale).

Returns:

String unique event identifier,

Throws:

IllegalEventDefinedException -

unregisterEvent

public void unregisterEvent(java.lang.String id)

Unregister the event specified by the event identifier. If the event does not exist then fail silently.

Parameters:

String - unique event identifier.