wt.events
Class StandardKeyedEventDispatcher

java.lang.Object
  wt.events.StandardKeyedEventDispatcher

All Implemented Interfaces:

KeyedEventDispatcher

public class StandardKeyedEventDispatcher
extends Object
implements KeyedEventDispatcher

Reference implementation of a KeyedEventDispatcher. This class implements a synchronous "in thread/transaction" dispatch of event notifications. There are two forms of dispatch, vetoable and non-vetoable. Vetoable event dispatches provide the ability for listeners to object to the consequence of an event by throwing an exception of a type prescribed by the event generator.

Events are dispatched synchronously in the thread of the event generator. Consequently, listeners are expected to respond to the event quickly. All side effects of the listeners actions will be in the same thread and transaction of the event generator and so the listener must be desiged to "play nice".

Veto listeners are notified of vetoable events when their notifyVetoableEvent method is invoked. Veto listeners may object to the event by throwing an exception of a type prescribed by the event generator. Note that since the events package is a general purpose package it cannot enforce type safe exceptions. It is up to the developer to make sure that an exception of the correct type is thrown.

Supported API: true

Extendable: false

See Also:

KeyedEvent, KeyedEventDispatcher

Method Summary

KeyedEventBranch	addEventBranch(String eventKey, String eventClassName, String eventType) Create and register an event key branch.
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.
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.

Methods inherited from class java.lang.Object

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

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

Specified by:

addEventBranch in interface KeyedEventDispatcher

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

Specified by:

getEventBranch in interface KeyedEventDispatcher

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

Specified by:

removeEventBranch in interface KeyedEventDispatcher

Parameters:

eventKey -

Returns:

KeyedEventBranch

getAllEventBranches

public Enumeration getAllEventBranches()

Return all event branches

Supported API: true

Specified by:

getAllEventBranches in interface KeyedEventDispatcher

Returns:

Enumeration

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

Specified by:

removeEventListener in interface KeyedEventDispatcher

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

Specified by:

dispatchEvent in interface KeyedEventDispatcher

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

Specified by:

dispatchVetoableEvent in interface KeyedEventDispatcher

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

Specified by:

dispatchMultiObjectEvent in interface KeyedEventDispatcher

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

Specified by:

dispatchVetoableMultiObjectEvent in interface KeyedEventDispatcher

Parameters:

event -

eventKey -

Throws:

WTException