org.barracudamvc.core.event
Class DefaultEventBroker

java.lang.Object
  extended by org.barracudamvc.core.event.DefaultEventBroker
All Implemented Interfaces:
EventBroker

public class DefaultEventBroker
extends Object
implements EventBroker

An EventBroker is responsible for two basic tasks:

  1. it serves as a registry for listeners to express interest in in events (or to make themselves generally available)
  2. it serves as the central point in a system for dispatching events to interested parties.

Typically, only the ApplicationGateway will actually dispatch events using the event broker.

There are two ways to register for Events. One is to specify the type of Event you're interested in. The other is simply to register a listener for general availability...anything addressed to that listener will be delivered. Note that when we're registering listeners, we're really registering listener factories. This allows the broker not to worry about syncronization issues, assuming that the factory will take care of that detail.

Note that when adding listeners, the broker calculates aliases for both listener IDs and events. This allows you to reference listeners and events by using just the class name instead of having to use the fully qualified class name. You can also add/remove aliases manually. Note however, that aliases are never automatically removed by the system, even when you remove listeners. This is because there is no way of knowing how _many_ listeners correspond with a particular alias. So...we just leave the aliases registered. In practice, this shouldn't really impact things as most listeners will only be deregistered at the end of the servlet lifecycle.

When there is more than one id for a given alias, the broker treats it as an ambiguous case and returns no match for that particular alias.

The event extension is used by whatever instantiates the broker (usually an ApplicationGateway) to define the particular event extension this broker is handling).


Field Summary
protected  DispatcherFactory dispatcherFactory
           
protected  Map eventMap
           
protected  Map eventXref
           
protected  String extension
           
protected  Map idMap
           
protected  Map idXref
           
protected static org.apache.log4j.Logger logger
           
 
Constructor Summary
DefaultEventBroker(DispatcherFactory idispatcherFactory, String iextension)
          Public constructor
 
Method Summary
protected  void addAliases(String id, List aliases, Map xref)
          Given an id and a list of aliases, add them to the specified xref
 void addEventAlias(Class event)
          Manually register aliases for a given event (the aliases will be determined automatically based on the class name and the event ID)
 void addEventAlias(Class event, String alias)
          Manually add an alias for a given event.
 void addEventListener(ListenerFactory factory)
          register a listener id, so that events addressed to a specific listener can be delivered
 void addEventListener(ListenerFactory factory, Class event)
          add an event listener for a particular class of an event.
 void dispatchEvent(EventContext context)
          Dispatch a queue of events.
protected  List getAliases(String className)
          The purpose of this method is to take a fully qualified class name and return a list of aliases for it.
 String getEventExtension()
          Return the event extension handled by this event broker
 ListenerFactory getEventListener(Object id)
          Get a specific listener based on listener ID
 List getEventListeners(Class event)
          Get a List of listeners for a type of event.
static void main(String[] args)
           
 String matchEventClass(String eventStr)
          Given a partial event class name, return the fully qualified class name if it's possible to determine.
 String matchListenerID(String idStr)
          Given a partial id name, return the fully qualified listener ID if it's possible to determine.
 void purgeEventListener(ListenerFactory factory)
          remove all references to an event listener, both for id and for any event classes it has registered an interest in.
 void removeEventListener(ListenerFactory factory)
          remove a listener from general availability
 void removeEventListener(ListenerFactory factory, Class event)
          remove an event listener for specific types of events If the class referenced is not an instance of BaseEvent, a InvalidClassException will be thrown.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

logger

protected static final org.apache.log4j.Logger logger

idMap

protected Map idMap

eventMap

protected Map eventMap

idXref

protected Map idXref

eventXref

protected Map eventXref

extension

protected String extension

dispatcherFactory

protected DispatcherFactory dispatcherFactory
Constructor Detail

DefaultEventBroker

public DefaultEventBroker(DispatcherFactory idispatcherFactory,
                          String iextension)
Public constructor

Parameters:
idispatcherFactory - a reference to the dispatcher factory to be used in creating dispatchers
iextension - the extension to be associated with all events delivered through the dispatcher
Method Detail

getEventExtension

public String getEventExtension()
Return the event extension handled by this event broker

Specified by:
getEventExtension in interface EventBroker
Returns:
the event extension associated with this broker

addEventListener

public void addEventListener(ListenerFactory factory)
register a listener id, so that events addressed to a specific listener can be delivered

Specified by:
addEventListener in interface EventBroker
Parameters:
factory - the listener factory to be added

addEventListener

public void addEventListener(ListenerFactory factory,
                             Class event)
                      throws InvalidClassException
add an event listener for a particular class of an event. If the class referenced is not an instance of BaseEvent, a ClassNotEventException will be thrown. Note that this method also registers the listener in the idMap as well.

Specified by:
addEventListener in interface EventBroker
Parameters:
factory - the listener factory to be added
event - the specific class of event for which the factory is listening
Throws:
InvalidClassException - if the event class does not implement BaseEvent

removeEventListener

public void removeEventListener(ListenerFactory factory)
remove a listener from general availability

Specified by:
removeEventListener in interface EventBroker
Parameters:
factory - the listener factory to be removed

removeEventListener

public void removeEventListener(ListenerFactory factory,
                                Class event)
                         throws InvalidClassException
remove an event listener for specific types of events If the class referenced is not an instance of BaseEvent, a InvalidClassException will be thrown. Note that this method effectively deregisters the listener from the idMap as well.

Specified by:
removeEventListener in interface EventBroker
Parameters:
factory - the listener factory to be removed
event - the specific class of event for which the factory is listening
Throws:
InvalidClassException - if the event class does not implement BaseEvent

purgeEventListener

public void purgeEventListener(ListenerFactory factory)
remove all references to an event listener, both for id and for any event classes it has registered an interest in.

Specified by:
purgeEventListener in interface EventBroker
Parameters:
factory - the listener factory to be removed

getEventListener

public ListenerFactory getEventListener(Object id)
Get a specific listener based on listener ID

Specified by:
getEventListener in interface EventBroker
Parameters:
id - the listener id we're looking for
Returns:
the ListenerFactory that matches that id

getEventListeners

public List getEventListeners(Class event)
                       throws InvalidClassException
Get a List of listeners for a type of event. Returns a copy of the broker's internal list, so you can do what you want with it. If the class referenced is not an instance of BaseEvent, a InvalidClassException will be thrown.

Specified by:
getEventListeners in interface EventBroker
Parameters:
event - the event class we are looking for
Returns:
a List of listeners that are interested in this class of event
Throws:
InvalidClassException - if the event class does not implement BaseEvent

matchEventClass

public String matchEventClass(String eventStr)
                       throws InvalidClassException
Given a partial event class name, return the fully qualified class name if it's possible to determine. If it is unknown, throw and InvalidClassException. This method is primarily used by the ApplicationGateway to support event aliasing.

Specified by:
matchEventClass in interface EventBroker
Parameters:
eventStr - the event name alias
Returns:
the fully qualified event class name
Throws:
InvalidClassException - if the eventStr cannot be unambiguously matched to a class name

matchListenerID

public String matchListenerID(String idStr)
                       throws InvalidClassException
Given a partial id name, return the fully qualified listener ID if it's possible to determine. If it is unknown, throw and InvalidClassException. This method is primarily used by the ApplicationGateway to support id aliasing.

Specified by:
matchListenerID in interface EventBroker
Parameters:
idStr - the id name alias
Returns:
the fully qualified listener id name
Throws:
InvalidClassException - if the idStr cannot be unambiguously matched to a listener id name

getAliases

protected List getAliases(String className)
The purpose of this method is to take a fully qualified class name and return a list of aliases for it. For instance, foo.blah.event.Test would generate the following aliases:


addEventAlias

public void addEventAlias(Class event)
                   throws InvalidClassException
Manually register aliases for a given event (the aliases will be determined automatically based on the class name and the event ID)

Specified by:
addEventAlias in interface EventBroker
Parameters:
event - the specific class of event we'd like to alias
Throws:
InvalidClassException - if the event class does not implement BaseEvent

addEventAlias

public void addEventAlias(Class event,
                          String alias)
                   throws InvalidClassException
Manually add an alias for a given event. Note that the alias parameter will be converted into all possible aliases based on '.' delimiters.

Specified by:
addEventAlias in interface EventBroker
Parameters:
event - the specific class of event we'd like to alias
alias - the alias for this event
Throws:
InvalidClassException - if the event class does not implement BaseEvent

addAliases

protected void addAliases(String id,
                          List aliases,
                          Map xref)
Given an id and a list of aliases, add them to the specified xref


dispatchEvent

public void dispatchEvent(EventContext context)
                   throws EventException

Dispatch a queue of events. Generally, the queue will only contain one event, however, if you ever need to dispatch multiple events at once, the broker can handle it. All the real dispatching work is carried out by the underlying event dispatcher.

The event queue you pass in should contain several pieces of state information:

Specified by:
dispatchEvent in interface EventBroker
Parameters:
context - the EventContext to be dispatched
Throws:
EventException

main

public static void main(String[] args)


Copyright © 2006 BarracudaMVC.org All Rights Reserved.