Firing events

Events, in the Zero platform, are a mechanism to orchestrate invocations of loosely coupled handlers. The Zero platform defines common events for Zero applications.

Developers can leverage Zero's event infrastructure to define their own events. Although this feature is not generally required for most application developers, it enables advanced developers to build custom, first-class extensions to Zero.

EventEngine.fire

Events are fired using static methods on the EventEngine:

public class EventEngine {
  public static EventContext fire(String eventName, Map eventData)
    throws FileNotFoundException, NoSuchMethodException {...}

  public static EventContext fire(String eventName, Map eventData,
                                  EventDispatcher dispatcher)
    throws FileNotFoundException, NoSuchMethodException {...}

where

• eventName is the event name
• eventData is made available to the invoked handlers in the event zone
• dispatcher drives the "firing" action, including exit conditions and Exception handling

Default event dispatcher

Invoking EventEngine.fire(eventName, eventData) employs a default EventDispatcher, which drives the following "firing" actions:

1. Obtain a list of the registered event handlers that "match" the event and current state (matching the state is based upon evaluating the conditions associated with the handlers); ordering is determined by the order in which the handlers were registered
2. Invoke the first handler with an event zone comprised of instance properties and named groups for that handler, along with eventData.
3. Repeat from step #2 with the next handler (until the entire list has been processed)
4. Return the event zone from the last handler

These actions terminate if any handler throws an Exception.

Custom event dispatchers

The "firing" actions may be modified with a custom EventDispatcher. The extension points, relative to the default event dispatcher, are noted in red:

1. Obtain a list of the registered event handlers that "match" the event and current state (matching the state is based upon evaluating the conditions associated with the handlers); ordering is determined by the order in which the handlers were registered
2. Collect a list of dynamically-resolved handlers by firing the =resolveHandlers= event.
3. Invoke the first handler with an event zone comprised of instance properties and named groups for that handler, along with eventData.
4. Determine whether to continue invoking handlers by checking the Global Context state
5. Repeat from step #3 with the next handler (until the entire list has been processed)
6. Return the event zone from the last handler

Exceptions may be caught and processed within the event dispatcher.

Custom event dispatchers extend EventDispatcher:

public class EventDispatcher {
  // Optional to implement exception handling and early exit criteria
  public boolean invoke(HandlerInfo handlerInfo)
    throws FileNotFoundException, NoSuchMethodException {

    // call super.invoke(handlerInfo) to invoke the handler

  }

  // Optional to implement step #2 above (dynamically resolving handlers)
  public List<HandlerData> resolveHandlers(List<HandlerData> configuredHandlers, 
                                           Map<String, ? extends Object> eventData)
    throws FileNotFoundException, NoSuchMethodException {

    // call getResolvedHandlers(eventData), which returns List<HandlerData>

  }
}

Special event dispatchers

Zero includes a set of EventDispatchers for common patterns.

WhileDispatcher

zero.core.events.dispatcher.WhileDispatcher continues the firing action as long as the specified condition is met. The condition is specified to the constructor.

For example:

Condition notEventDone =
    new NotCondition(new SelectorCondition("/event/done", "true"));
WhileDispatcher dispatcher = new WhileDispatcher(notEventDone);
EventEngine.fire("eventName", null, dispatcher);

OneDispatcher

zero.core.events.dispatcher.OneDispatcher is designed to run one handler. OneDispatcher is used to handle the request events (GET, PUT, POST, DELETE).

Characteristics:

• resolveHandlers invokes getResolvedHandlers() only if there are no configured handlers (efficiency)
• resolveHandlers throws a FileNotFoundException if no handlers are found
• If at least one handler is found, then only the first handler is invoked

OneOrNoneDispatcher

zero.core.events.dispatcher.OneOrNoneDispatcher is similar to the OneDispatcher, except that finding "no handlers" does not cause a FileNotFoundException.