Repository: qpid-proton Updated Branches: refs/heads/proton-j-reactor 09c190f2b -> 2405ca0f1
PROTON-881: added a README with a bit of explanation of the reactor processing model Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/2405ca0f Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/2405ca0f Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/2405ca0f Branch: refs/heads/proton-j-reactor Commit: 2405ca0f1bd2cd7933cd335ead8de42fd2dc072c Parents: 09c190f Author: Rafael Schloming <[email protected]> Authored: Fri May 15 14:32:54 2015 -0400 Committer: Rafael Schloming <[email protected]> Committed: Fri May 15 14:32:54 2015 -0400 ---------------------------------------------------------------------- examples/java/reactor/README.md | 55 ++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/2405ca0f/examples/java/reactor/README.md ---------------------------------------------------------------------- diff --git a/examples/java/reactor/README.md b/examples/java/reactor/README.md new file mode 100644 index 0000000..dcbcb89 --- /dev/null +++ b/examples/java/reactor/README.md @@ -0,0 +1,55 @@ +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. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
