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

Field Summary

private static String	CLASSNAME
private String	dispatcherName
private Hashtable	keyedEventBranches
private static String	RESOURCE

Fields inherited from interface wt.events.KeyedEventDispatcher

EVENT_KEY_DELIMITER, EVENT_KEY_ROOT

Constructor Summary

StandardKeyedEventDispatcher()
Default no-argument constructor

Supported API: false

StandardKeyedEventDispatcher(String dispatcherName)
Constructor which provides the ability to name a dispatcher instance.

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.
static String	generateClassKey(Class targetClass) Utility used to generate a key for a class.
static String	generateEventKey(String[] args) Utility used to generate an 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.
Vector	getKeyedEventBranches() Gets the object for the association that plays role: keyedEventBranches.
void	intDispatchEvent(Object event, String eventKey, boolean isSingleObjectEvent, boolean isVetoable)
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.
void	setKeyedEventBranches(Vector a_KeyedEventBranches) Sets the object for the association that plays role: keyedEventBranches.
protected String	truncateEventKey(String eventKey) Utility used to "climb the event tree"; strips off the trailing key token yielding the event key of the parent branch.

Methods inherited from class java.lang.Object

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

Field Detail

RESOURCE

private static final String RESOURCE

See Also:

Constant Field Values

CLASSNAME

private static final String CLASSNAME

dispatcherName

private String dispatcherName

keyedEventBranches

private Hashtable keyedEventBranches

Constructor Detail

StandardKeyedEventDispatcher

public StandardKeyedEventDispatcher(String dispatcherName)

Constructor which provides the ability to name a dispatcher instance.

Supported API: false

Parameters:

dispatcherName - The name of the StandardEventDispatcher, may be null

StandardKeyedEventDispatcher

public StandardKeyedEventDispatcher()

Default no-argument constructor

Supported API: false

Method Detail

generateEventKey

public static String generateEventKey(String[] args)

Utility used to generate an event key. Concatinates a set of string arguments with a standard delimiter. The event key root, "*", is the first token in the event key, if the arguments do not include "*" as the first token it will be inserted automatically.

Supported API: false

Parameters:

args - the components of the event key, if no args are supplied then the root event key "*" is returned.

Returns:

String

generateClassKey

public static String generateClassKey(Class targetClass)

Utility used to generate a key for a class. The names of the all superclasses (not interfaces) except java.lang.Object are combined with the target class name to form a key. This key is often used as a ub-key. Note that this operation only follows the class hierarchy and does not use the interfaces that the class implements.

Note that the structure of event keys may vary from one situation to another. This operation is just a utility and need not necessarily be used to generate keys.

Supported API: false

Parameters:

targetClass - the class to form a key for.

Returns:

String

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

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

Specified by:

addEventListener in interface KeyedEventDispatcher

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

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

printAllEventBranches

public void printAllEventBranches()

Print all event branches

Supported API: false

Specified by:

printAllEventBranches in interface KeyedEventDispatcher

truncateEventKey

protected String truncateEventKey(String eventKey)

Utility used to "climb the event tree"; strips off the trailing key token yielding the event key of the parent branch.

Supported API: false

Parameters:

eventKey -

Returns:

String

getKeyedEventBranches

public Vector getKeyedEventBranches()

Gets the object for the association that plays role: keyedEventBranches.

Supported API: false

Returns:

Vector

setKeyedEventBranches

public void setKeyedEventBranches(Vector a_KeyedEventBranches)
                           throws WTPropertyVetoException

Sets the object for the association that plays role: keyedEventBranches.

Supported API: false

Parameters:

a_KeyedEventBranches -

Throws:

WTPropertyVetoException

intDispatchEvent

public void intDispatchEvent(Object event,
                             String eventKey,
                             boolean isSingleObjectEvent,
                             boolean isVetoable)
                      throws WTException

Throws:

WTException