[28/38] qpid-proton git commit: PROTON-881: added a README with a bit of explanation of the reactor processing model

[rh...@apache.org]

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/master
Commit: 2405ca0f1bd2cd7933cd335ead8de42fd2dc072c
Parents: 09c190f
Author: Rafael Schloming <rh...@alum.mit.edu>
Authored: Fri May 15 14:32:54 2015 -0400
Committer: Rafael Schloming <rh...@alum.mit.edu>
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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org