wt.events
Interface KeyedEventDispatcher

All Known Subinterfaces:

ManagerService

All Known Implementing Classes:

StandardKeyedEventDispatcher, StandardManagerService

public interface KeyedEventDispatcher

Interface for event subscription and notification. Events are identified and categorized by event keys. When a listener subscribes to an event it provides an event key which indicates which events interest the listener. For example an event key with value "Manager/STARTED/PM" indicates the Manager started event for the Pesistence Manager.

The set of subscription event keys form a logical tree hierarchy. Each branch in the event key hierarchy is an KeyedEventBranch. Each instance of KeyedEventBranch is identified by an event key. The root of the event key hierarchy is "*". The root key "*" identifies all events and is implicitly or explicitly included in all event keys. For example, if the set of event keys includes "Manager/STARTED/PM", "Manager/SHUTDOWN/PM", "Manager/STARTED/LockManager", PM/CREATE/Customer" and "PM/DELETE/Customer" then the event key tree would be as follows:

Level 1: "*"
Level 2: "Manager", "PM"
Level 3: "Manager/STARTED", "Manager/SHUTDOWN", "PM/CREATE", "PM/DELETE"
Level 4: "Manager/STARTED/PM", "Manager/SHUTDOWN/PM", "Manager/STARTED/LockManager", "PM/CREATE/Customer", "PM/DELETE/Customer"

When an event is dispatched an event key which identifies and classifies the event must be provided. The algorithm for dispatching an event is as follows:

1. Locate the branch which matches the event key. For example event key "PM/DELETE/Customer" matches the bottom right leaf branch of the event tree.
2. Dispatch the event to all listeners for the branch which matches the event key.
3. If the event key branch is not the root branch then locate the parent branch for the current branch.
4. Dispatch the event to all listeners for the branch.
5. While the current branch is not the root branch repeat steps 3 and 4

Notice that this event dispatching mechanism allows a listener to subscribe to more or less specific categories of events. In this example the listener may subscribe to the manager started event for LockManagers or all manager started events or all manager events or all events.

Supported API: true

Extendable: false

See Also:

KeyedEventBranch, StandardKeyedEventDispatcher

Field Summary

static String	EVENT_KEY_DELIMITER Supported API: false
static String	EVENT_KEY_ROOT Supported API: false

Method Summary

KeyedEventBranch	addEventBranch(String eventKey, String eventClassName, String eventType) Create and register an event key branch.
void	addEventListener(KeyedEventListener listener, String eventKey) Add a synchronous "in thread/transaction" event listener.
void	dispatchEvent(Object event, String eventKey) Dispatch a non-vetoable single-object event to all listeners for the event key.
void	dispatchMultiObjectEvent(Object event, String eventKey) Dispatch a non-vetoable multi-object event to all listeners for the event key.
void	dispatchVetoableEvent(Object event, String eventKey) Dispatch a vetoable single-object event to all listeners for the event key.
void	dispatchVetoableMultiObjectEvent(Object event, String eventKey) Dispatch a vetoable multi-object event to all listeners for the event key.
Enumeration	getAllEventBranches() Return all event branches Supported API: true
KeyedEventBranch	getEventBranch(String eventKey) Return the event key branch which exactly matches the event key.
void	printAllEventBranches() Print all event branches Supported API: false
KeyedEventBranch	removeEventBranch(String eventKey) Locate and remove the event key branch which exactly matches the event key.
void	removeEventListener(KeyedEventListener listener, String eventKey) Remove an event listener.

Field Detail

EVENT_KEY_ROOT

public static final String EVENT_KEY_ROOT

Supported API: false

See Also:

Constant Field Values

EVENT_KEY_DELIMITER

public static final String EVENT_KEY_DELIMITER

Supported API: false

See Also:

Constant Field Values

Method Detail

addEventBranch

public KeyedEventBranch addEventBranch(String eventKey,
                                       String eventClassName,
                                       String eventType)
                                throws IllegalArgumentException

Create and register an event key branch. If the branch already exists an InvalidArgumentException is thrown.

Supported API: true

Parameters:

eventKey -

eventClassName -

eventType -

Returns:

KeyedEventBranch - a new or existing event key branch.

Throws:

IllegalArgumentException

getEventBranch

public KeyedEventBranch getEventBranch(String eventKey)

Return the event key branch which exactly matches the event key.

Supported API: true

Parameters:

eventKey -

Returns:

KeyedEventBranch

removeEventBranch

public KeyedEventBranch removeEventBranch(String eventKey)

Locate and remove the event key branch which exactly matches the event key. All listeners are removed from the branch.

Supported API: true

Parameters:

eventKey -

Returns:

KeyedEventBranch

getAllEventBranches

public Enumeration getAllEventBranches()

Return all event branches

Supported API: true

Returns:

Enumeration

addEventListener

public void addEventListener(KeyedEventListener listener,
                             String eventKey)

Add a synchronous "in thread/transaction" event listener. The listener is added to the list of listeners for the event key branch which matches the event key.

Supported API: false

Parameters:

listener - the listener to be added.

eventKey - the key which identifies the branch for listening.

removeEventListener

public void removeEventListener(KeyedEventListener listener,
                                String eventKey)

Remove an event listener. The listener is removed from the list of listeners for the event key branch which matches the event key.

Supported API: true

Parameters:

listener - the listener to be removed

eventKey - the key which identifies the branch from wihch to remove

dispatchEvent

public void dispatchEvent(Object event,
                          String eventKey)

Dispatch a non-vetoable single-object event to all listeners for the event key. The listener may not object to the event.

Perform a synchronous "in thread/transaction" notification of each event listener for the event branch identified by the event key. Call the notifyEvent operation on each subscriber. If a multi-object notifyMultiObjectEvent exists for a subscriber, convert the single-object event to an multi-object event and call the multi-object subscriber's notifyMultiObjectEvent.

Supported API: true

Parameters:

event - the event to be dispatched

eventKey - the key of the event branch which has the subscribers

dispatchVetoableEvent

public void dispatchVetoableEvent(Object event,
                                  String eventKey)
                           throws WTException

Dispatch a vetoable single-object event to all listeners for the event key. If the listener objects to the event the listener may throw an exception.

Perform a synchronous "in thread/transaction" notification of each event listener for the event branch identified by the event key. Call the notifyVetoableEvent operation on each subscriber. If a multi-object notifyVetoableMultiObjectEvent exists for a subscriber, convert the single-object event to an multi-object event and call the multi-object subscriber's notifyVetoableMultiObjectEvent. If the subscriber objects to the event is may throw an excpetion which will be returned to the operation invoker. It is upto the dispatch invoker and the exception thrower to agree on what exception is to be thrown.

Supported API: true

Parameters:

event -

eventKey -

Throws:

WTException

dispatchMultiObjectEvent

public void dispatchMultiObjectEvent(Object event,
                                     String eventKey)

Dispatch a non-vetoable multi-object event to all listeners for the event key. The listener may not object to the event.

Perform a synchronous "in thread/transaction" notification of each event listener for the event branch identified by the event key. Call the notifyMultiObjectEvent operation on each subscriber. If a single-object notifyEvent exists for a subscriber, convert the multi-object event to an array of single-object events and loop over the single-object subscriber's notifyEvent.

Supported API: true

Parameters:

event - the event to be dispatched

eventKey - the key of the event branch which has the subscribers

dispatchVetoableMultiObjectEvent

public void dispatchVetoableMultiObjectEvent(Object event,
                                             String eventKey)
                                      throws WTException

Dispatch a vetoable multi-object event to all listeners for the event key. If the listener objects to the event the listener may throw an exception.

Perform a synchronous "in thread/transaction" notification of each event listener for the event branch identified by the event key. Call the notifyVetoableMultiObjectEvent operation on each subscriber. If a single-object notifyVetoabelEvent exists for a subscriber, convert the multi-object event to an array of single-object events and loop over the single-object subscriber's notifyVetoableEvent. If the subscriber objects to the event is may throw an excpetion which will be returned to the operation invoker. It is upto the dispatch invoker and the exception thrower to agree on what exception is to be thrown.

Supported API: true

Parameters:

event -

eventKey -

Throws:

WTException

printAllEventBranches

public void printAllEventBranches()

Print all event branches

Supported API: false