Simon Wacker

An event is every change in an application an event handler receives. Events are for example triggered if a certain point in an application is reached or if a user interacts with the application. In theory everything can trigger events. An event-driven API normally consists of two main modules.

• A dispatcher is responsible for dispatching the event to multiple event handlers. Dispatchers are also called broadcasters, distributors, publishers and multicasters.
• Event Handlers are responsible for handling events. They receive the event and operate in accordance with it. They may also consume the event and thus stop the event to be dispatched to further event handlers. Event handlers are also called listeners, subscribers and observers.

In most event APIs, event handlers can register themselves at a dispatcher. If an event occurs the dispatcher then dispatches the event to all registered event handlers. Thus the dispatcher has two main responsibilites.

• Managing a collection of event handlers.
• Dispatching events to all registered event handlers if they occur and maybe managing an event queue that holds unprocessed events.

Some dispatchers also support the consumption of events. The dispatcher then dispatches an event to event handlers step-by-step, until an event handler consumes the event. This is sometimes called to veto to an event.

Events are used when there is more than one object or there are an unknown number of objects that may want to be notified if some specific operation took place. For example if a user pressed a button. It is bad pracitice to use events for every interaction between objects because this adds unnecessary complexity and slows the execution of the program down. So, think carefully if using events really benefits your application in your specific case.

The Observer Design Pattern is closely related to events. The “Subject” is analog to the “Dispatcher” and the “Observer” to the “Event Handler”. Reading the Observer’s intent you can clearly see the connection: “Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically.”.

In the As2lib Event API we call event handlers listeners and thus a collection of event handlers listener source. The “EventListenerSource” interface declares common methods needed to manage a collection of listeners. A listener source is so to speak a data holder that holds listeners. The As2lib Event API offers two types of listener sources.

• The “SimpleEventListenerSource” manages listeners in the simplest way possible.
• The “TypeSafeEventListenerSource” manages listeners and ensures that it contains only listeners of a specific type.

Depending on your event handling implementation you may not need a type-safe listener source because you may have ensured the correct type of the listeners somehow else. In such a case use the simple listener source or the type-safe listener source with a flag that the type shall not be checked. Otherwise use the type-safe listener source because it prevents unexpected behavior caused by wrong listeners.

This As2lib Broadcaster Event API is built around the “EventBroadcaster” interface. This interface combines listener source and dispatch functionalities. The “dispatch” method expects exactly one parameter that must be of type “EventInfo”. This event info is also passed-to the listeners. It holds at least the name of the event that is also the name of the method to invoke on the listeners, the event method. It may also contain any additional information. The normal process when working with this API is as follows:

• Creating a listener interface that declares the event method. This event method takes one parameter that must be of type “EventInfo” or a sub-interface or implementation-class.
  1. interface MyListener {
  2.     public function onMyEvent(myEventInfo:MyEventInfo):Void;
  3. }
  4.  
• Creating the specific event info class that has been used as type for the event method’s parameter. This class must implement the “EventInfo” interface. The “getName” method should return a hard-coded string, the name of the event method.
  1. class MyEventInfo implements EventInfo {
  2.     private var information:String;
  3.     public function MyEventInfo(information:String) {
  4.         this.information = information;
  5.     }
  6.     public function getInformation(Void):String {
  7.         return this.information;
  8.     }
  9.     public function getName(Void):String {
  10.         return "onMyEvent";
  11.     }
  12. }
  13.  

In your application you instantiate an event broadcaster for every event, listeners can register to and implement the appropriate add and remove methods that should be properly typed to the listener interfaces. Now when an event occurs you instantiate the appropriate event info with all needed information and dispatch to the added listeners with the appropriate broadcaster passing-in the instantiated event info.

The advantages of this approach are:

• If the event method’s name of a listener changes there is only one place to change the event method’s name, the event info class.
• Because of your typed methods to add and remove listeners you ensure that only listeners that really implement the expected interface are added, so there is no need for further type-checking by the listener source, which leads to better performance.
• Because of your event info class that contains all event specific information you are not bloating the event method’s parameter list. Note though that in the above case this would not have been necessary because we have only one information.
• This approach is rather fast because it does not have to make any detours.
• This approach does not prescribe the existence of a listener interface or class. Note that I myself think of not declaring an explicit listener type as bad practice.
• If one of the listeners needs more information one can simply extend the event info without having to alter other listeners.

But there are also many disadvantages:

• The compiler does not check whether the event method’s name on the listener and the one in the event info class are in sync.
• The listener must always get its information from the passed-in event info. If there is no information needed or if the information needed is only one value, as in the above example, an event info is overkill and unintuitive.
• The listener is bound or has a dependency to the As2lib Broadcaster Event API because it declares one parameter of type “EventInfo”.
• There must be one, in some cases unnecessary class, the “EventInfo” implementation.

Let’s move on and take a look at the As2lib Multicaster Event API that eliminates some of the disadvantages, but adds some new ones.

The core interface of the As2lib Multicaster Event API is the “EventMulticaster”. This interface combines, like the “EventBroadcaster” interface of the previous tutorial page, listener source and dispatch functionalities. The difference is that this time the “dispatch” method expects any number of parameters of any type that are passed-to the event methods of all registered listeners; the listener interface is thus not bound to an event info and a specific event API. All the rest stays basically the same.

The advantages are:

• We do not bind our listeners anymore to a specific event API by allowing custom parameters.
• We can still package information/parameters into one data transfer object if we want to, but it is not prescribed. And this object also does not have to extend or implement a specific class or interface.
• Dispatching events and declaring listeners feels much more natural and is more intutitive.

But again this is connected with some disadvantages:

• The name of the event method is in most implementations passed-in on instantiation of every event multicaster. This is more error-prone because it is easy to make a typo. If the listener’s event method’s name changes we also have to change the event method name in multiple locations.
• Compile-time checking of whether the event method’s name on the listener and the ones we pass-to our event multicasters is still not given.

Again, there issstill much that can be improved; most notably the lack of compile-time checking. This issue is addressed by the As2lib Distributor Event API, so go on.

Unlike the previously discussed event APIs, this API’s base interface is not a dispatcher but a dispatcher control: “EventDistributorControl”. This interface acts as a listener source and a provider and controller of a typed distributor. You again create such a control per event providing it the listener interface or class.

You can then use this control to add and remove listeners.

If the event occurs you first get a typed distributor from the control and invoke the event method on it passing-in the appropriate parameters. The neat thing about this is that you get compile-time checking whether the method you are invoking exists and whether the parameters are of correct type.

The advantages are obvious:

• You have proper compile-time checking when dispatching the event; type-checking of parameters and existence-checking of method.
• You can have proper type-checking of listeners because you specified the expected listener type.
• You can use custom parameters and are not bound to an event info. But if you want to package the information in one object you are free to do so; this object must not extend or implement any specific class or interface, its just a design choice.
• The listener is not bound to any specific event API.

One disadvantage may be that if the name of the event method on the listener changes you have to make a change in every place where you dispatch events. But the compiler tells you that and where these changes have to be made. A good IDE also changes all calls to the method automatically if you change the method’s name. So, this is not much of an issue.