Package 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:

  • Method Details

    • addEventBranch

      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

      KeyedEventBranch getEventBranch(String eventKey)
      Return the event key branch which exactly matches the event key.

      Supported API: true
      Parameters:
      eventKey -
      Returns:
      KeyedEventBranch

    • removeEventBranch

      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

      Enumeration getAllEventBranches()
      Return all event branches

      Supported API: true
      Returns:
      Enumeration

    • addEventListener

      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: true
      Parameters:
      listener - the listener to be added.
      eventKey - the key which identifies the branch for listening.

    • removeEventListener

      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

      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

      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

      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

      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