org.exolab.jms.events
Class BasicEventManager

java.lang.Object
  |
  +--org.exolab.jms.service.Service
        |
        +--org.exolab.jms.service.BasicService
              |
              +--org.exolab.jms.events.BasicEventManager

All Implemented Interfaces:

EventManager, java.lang.Runnable, Serviceable

public class BasicEventManager

extends BasicService

implements EventManager

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, 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.

Version:

$Revision: 1.4 $ $Date: 2006/02/23 11:17:38 $

Author:

Chris Wood

Constructor Summary

BasicEventManager(org.exolab.jms.common.threads.ThreadPoolFactory factory)
Construct a new BasicEventManager.

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	run()
void	unregisterEvent(java.lang.String id) Unregister the event specified by the event identifier.

Methods inherited from class org.exolab.jms.service.BasicService

doStart, doStop, toString

Methods inherited from class org.exolab.jms.service.Service

getName, isStarted, restart, start, stop

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

BasicEventManager

public BasicEventManager(org.exolab.jms.common.threads.ThreadPoolFactory factory)

Construct a new BasicEventManager.

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.

Specified by:

registerEvent in interface EventManager

Parameters:

event - information about the event

absolute - 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.

Specified by:

registerEventRelative in interface EventManager

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.

Specified by:

unregisterEvent in interface EventManager

Parameters:

id - unique event identifier.

run

public void run()