tree: 9618833904a3fed27ca9c2a7974c973b53d3eae0 [path history] [tgz]
  1. README.md
  2. pom.xml
  3. run
  4. src/
examples/reactor/README.md

The Reactor API provides a means to dispatch events occurring across one or more connections. It can be used purely as a dispatch tool alongside your own I/O mechanism, however by default it is configured with a handler that provides I/O for you.

When programming with the reactor it is important to understand the dispatch model used to process events. Every event is associated with a context object, i.e. the target object upon which the event occurred. These objects are contained either directly or indirectly within the Reactor:

Delivery --> Link --> Session --> Connection --+
                                               |
                                        Task --+--> Reactor
                                               |
                                  Selectable --+

Each event is dispatched first to a target-specific handler, and second to a global handler. The target-specific handler for an event is located by searching from the event context up through the hierarchy (terminating with the Reactor) and retrieving the most specific handler found.

This means that any handler set on the Reactor could receive events targeting any object. For example if no handlers are associated with a Connection or any of its child objects, then the Reactor's handler will receive all the events for that Connection.

Putting a handler on any child, e.g. a Connection or Session or Link will prevent any handlers set on the ancestors of that object from seeing any events targeted for that object or its children unless that handler specifically chooses to delegate those events up to the parent, e.g. by overriding onUnhandled and delegating.

The global handler (used to dispatch all events after the target-specific handler is invoked) can be accessed and modified using Reactor.set/getGlobalHandler. This can be useful for a number of reasons, e.g. you could log all events by doing this:

reactor.getGlobalHandler().add(new LoggerHandler());

Where LoggerHandler does this:

public void onUnhandled(Event evt) {
    System.out.println(evt);
}

The above trick is particularly useful for debugging.

Handlers themselves can have child handlers which will automatically delegate the event to those children after dispatching the event to itself. The default global handler is what provides the default I/O behavior of the reactor. To use the reactor as a pure dispatch mechanism you can simply set the global handler to null.