Firing events

Developers can use WebSphere sMash's event infrastructure to define their own events. The WebSphere sMash platform defines common events for WebSphere sMash applications. See the Event processing article for more information.

EventEngine.fire

Events are fired using static methods on the EventEngine as shown in the following example:

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 {...}
    

In this example, the following are used:

eventName

The event name

eventData

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, that 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. See the event-handler registration information in the Configuration article for details.
2. Invoke the first handler with an event zone comprised of instance properties and named groups for that handler, along with eventData. For more information, see the instance properties and named groups information in the Configuration article.
3. Repeat this process, beginning with 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. For more information about exception throwing, see the request-processing events information in the Event processing article.

Custom event dispatchers

The firing actions can be modified with a custom EventDispatcher. The extension points, relative to the default event dispatcher, are noted in steps 2 and 4 in the following steps:

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. For more information about registered event handlers, see the Configuration article.
2. Collect a list of dynamically-resolved handlers by firing the resolveHandlers event. For more information about the resolveHandlers event, see the Event processing article.
3. Invoke the first handler with an event zone comprised of instance properties named groups for that handler, along with eventData. For more information about instance properties and named groups, see the Configuration article.
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 can be caught and processed within the event dispatcher. Custom event dispatchers extend EventDispatcher, as shown in the following example:

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

WebSphere sMash includes a set of EventDispatchers for common patterns, as discussed in the following sections.

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, as shown in the following 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) and has the following 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

For more information about request events for example, GET, PUT, POST, DELETE, see the Event processing article.

OneOrNoneDispatcher

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