Category: Commons

In a de-coupled environment, its not always easy to let various components communicate with each other. In order to make this task slightly easier AS3Commons offers the EventBus.

The EventBus is used as a publish/subscribe event mechanism that lets objects communicate with eachother in a loosely coupled way.

A dependency injection mechanism can be used to inject a shared EventBus instance into the necessary application components.

Multiple EventBus instances can operate independently of each other or can optionally be chained to allow for inter-application or -module communication.

EventBus listeners

There are a number of different ways to subscribe to events that are dispatched through the EventBus:

public interface IEventBusListener {

 function onEvent(event:Event):void;

}

eventBus.addListener(listener);

eventBus.addEventListener("myCustomEvent", listenerFunction);

var methodInvoker:MethodInvoker = new MethodInvoker();
methodInvoker.target = someInstance;
methodInvoker.method = "listenerMethodName";
eventBus.addEventListenerProxy("myCustomEvent", methodInvoker);

eventBus.addEventClassListener(MyCustomEvent, listenerFunction);

eventBus.addListener(listener, true)

eventBus.addListener(eventBusListener, false, "myTopic");

EventBus dispatchers

This is the easiest part, to dispatch an event through anEventBusinvoke either the dispatchEvent() or dispatch() methods. The former expects an Event instance while the latter expects a string that indicates a certain type of Event. This event will be created by this method and subsequently dispatched. For example:

eventBus.dispatchEvent(new MyCustomEvent("myCustomEventType"));

or:

eventBus.dispatch("myCustomEventType");

eventBus.dispatchEvent(new MyCustomEvent("myCustomEventType"), "myTopic");

EventBus event interceptin

To prevent events from passing through the EventBus, or to change their properties before they do, an IEventBus implementation accepts IEventInterceptor registrations.

This process is almost the same as for event listeners: Interceptors can be added globally, for specific event types or specific classes and for specific topics.

eventBus.addInterceptor(interceptor);
eventBus.addEventInterceptor("myCustomEvent", interceptor);
eventBus.addEventClassInterceptor(MyCustomEvent, interceptor);
//And for topic specific interception:
eventBus.addInterceptor(interceptor, "myTopic");
eventBus.addEventInterceptor("myCustomEvent", interceptor, "myTopic");
eventBus.addEventClassInterceptor(MyCustomEvent, interceptor, "myTopic");

The IEventInterceptor interface is a very simple one and looks like this:

public interface IEventInterceptor extends IEventBusAware {
	function get blockEvent():Boolean;
	function set blockEvent(value:Boolean):void;
	function intercept(event:Event):void;
}

The intercept() method will be invoked for each event that passes through the EventBus and that adheres to the registration parameters of the IEventInterceptor.

To prevent the event to continue to be dispatched the blockEvent property can be set to true.

An IEventInterceptor also receives a reference to the current EventBus each time its intercept() method is invoked, this allows an implementation to block certain events and replace them with a different instance. Events could be split up into multiple events, etc.

AS3Comons-eventbus offers the AbstractEventInterceptor to be used as a general base class for event interceptors.

EventBus event listener intercepting

To log, modify or block event listeners from being added an IEventListenerInterceptor can be registered with the EventBus.

This process is almost the same as for event listeners and interceptors: Listener interceptors can be added globally, for specific event types or specific classes and for specific topics.

eventBus.addListenerInterceptor(interceptor);
eventBus.addEventListenerInterceptor("myCustomEvent", interceptor);
eventBus.addClassListenerInterceptor(MyCustomEvent, interceptor);
//And for topic specific interception:
eventBus.addListenerInterceptor(interceptor, "myTopic");
eventBus.addEventListenerInterceptor("myCustomEvent", interceptor, "myTopic");
eventBus.addClassListenerInterceptor(MyCustomEvent, interceptor, "myTopic");

To prevent the listener from being added, simply set the blockListener property to true.

An IEventListenerInterceptor also receives a reference to the current EventBus each time its interceptListener() or interceptListenerProxy() method is invoked, allowing the interceptor to examine the EventBus before deciding to allow the listener to be added or not.

AS3Comons-eventbus offers the AbstractEventListenerInterceptor to be used as a general base class for eventlistener interceptors.

Static EventBus implementation

In a select few cases it might be easier to have one static eventbus in an application, for this purpose as3-commons-eventbus offers the StaticEventBus.

The StaticEventBus has static equivalents of all the IEventBus methods, so its usage is exactly the same.

EventBus chaining

The EventBus itself is also an implementation of IEventBusListener. Therefore it is possible to chain multiple EventBus instances by adding an EventBus as a global listener to another EventBus.

In that case every event dispatched by the EventBus will be redispatched by the listening EventBus.

var eventBus1:EventBus = new EventBus();
var eventBus2:EventBus = new EventBus();
eventBus1.addListener(eventBus2, true);
eventBus1.dispatchEvent(new MyCustomEvent());
//MyCustomEvent will now also be dispatched through eventBus2...