qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@apache.org
Subject [1/4] qpid-proton git commit: PROTON-881: Tidy up proton-j reactor examples
Date Mon, 06 Jul 2015 00:06:30 GMT
Repository: qpid-proton
Updated Branches:
  refs/heads/master 46edaebeb -> 149725943


PROTON-881: Tidy up proton-j reactor examples

Tidy up comments and more closely mirror the Python examples.


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/14972594
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/14972594
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/14972594

Branch: refs/heads/master
Commit: 149725943f980241445b53ef9d6a6e97754af3fd
Parents: 2f8728a
Author: Adrian Preston <prestona@uk.ibm.com>
Authored: Wed Jul 1 01:22:55 2015 +0100
Committer: Rafael Schloming <rhs@alum.mit.edu>
Committed: Sun Jul 5 19:57:39 2015 -0400

----------------------------------------------------------------------
 .../apache/qpid/proton/example/reactor/Cat.java | 10 +++--
 .../proton/example/reactor/CountRandomly.java   |  1 +
 .../qpid/proton/example/reactor/Counter.java    |  7 +++-
 .../qpid/proton/example/reactor/Echo.java       | 14 +++++--
 .../proton/example/reactor/GlobalLogger.java    | 39 --------------------
 .../proton/example/reactor/GoodbyeWorld.java    |  6 +--
 .../qpid/proton/example/reactor/HelloWorld.java |  3 +-
 .../qpid/proton/example/reactor/README.md       | 31 ++++++++++++++++
 .../proton/example/reactor/ReactorLogger.java   | 34 -----------------
 .../qpid/proton/example/reactor/Recv.java       |  4 +-
 .../qpid/proton/example/reactor/Scheduling.java | 11 ++++++
 11 files changed, 71 insertions(+), 89 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Cat.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Cat.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Cat.java
index 7cc1df3..cb8ceca 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Cat.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Cat.java
@@ -38,14 +38,19 @@ public class Cat extends BaseHandler {
         @Override
         public void onSelectableInit(Event event) {
             Selectable selectable = event.getSelectable();
-            Reactor reactor = event.getReactor();
+            // We can configure a selectable with any SelectableChannel we want.
+            selectable.setChannel(channel);
+            // Ask to be notified when the channel is readable
             selectable.setReading(true);
-            reactor.update(selectable);
+            event.getReactor().update(selectable);
         }
 
         @Override
         public void onSelectableReadable(Event event) {
             Selectable selectable = event.getSelectable();
+
+            // The onSelectableReadable event tells us that there is data
+            // to be read, or the end of stream has been reached.
             SourceChannel channel = (SourceChannel)selectable.getChannel();
             ByteBuffer buffer = ByteBuffer.allocate(1024);
             try {
@@ -77,7 +82,6 @@ public class Cat extends BaseHandler {
     public void onReactorInit(Event event) {
         Reactor reactor = event.getReactor();
         Selectable selectable = reactor.selectable();
-        selectable.setChannel(channel);
         setHandler(selectable, new EchoHandler());
         reactor.update(selectable);
     }

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/CountRandomly.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/CountRandomly.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/CountRandomly.java
index 0dcdf4a..9a5a0b4 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/CountRandomly.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/CountRandomly.java
@@ -55,6 +55,7 @@ public class CountRandomly extends BaseHandler {
             }
         }
 
+        // Provide a method to check for doneness
         private boolean done() {
             return count >= limit;
         }

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Counter.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Counter.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Counter.java
index a34038e..b05685a 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Counter.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Counter.java
@@ -45,6 +45,8 @@ public class Counter extends BaseHandler {
             count += 1;
             System.out.println(count);
             if (count < limit) {
+                // A recurring task can be accomplished by just scheduling
+                // another event.
                 event.getReactor().schedule(250, this);
             }
         }
@@ -57,8 +59,9 @@ public class Counter extends BaseHandler {
 
         // Note that unlike the previous scheduling example, we pass in
         // a separate object for the handler. This means that the timer
-        // event we just scheduled will not be seen by Program as it is
-        // being handled by the Counter instance we create.
+        // event we just scheduled will not be seen by the Counter
+        // implementation of BaseHandler as it is being handled by the
+        // CounterHandler instance we create.
         event.getReactor().schedule(250, new CounterHandler(10));
     }
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Echo.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Echo.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Echo.java
index e2b0807..852bf8e 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Echo.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Echo.java
@@ -37,14 +37,19 @@ public class Echo extends BaseHandler {
         @Override
         public void onSelectableInit(Event event) {
             Selectable selectable = event.getSelectable();
-            Reactor reactor = event.getReactor();
+            // We can configure a selectable with any SelectableChannel we want.
+            selectable.setChannel(channel);
+            // Ask to be notified when the channel is readable
             selectable.setReading(true);
-            reactor.update(selectable);
+            event.getReactor().update(selectable);
         }
 
         @Override
         public void onSelectableReadable(Event event) {
             Selectable selectable = event.getSelectable();
+
+            // The onSelectableReadable event tells us that there is data
+            // to be read, or the end of stream has been reached.
             SourceChannel channel = (SourceChannel)selectable.getChannel();
             ByteBuffer buffer = ByteBuffer.allocate(1024);
             try {
@@ -74,10 +79,13 @@ public class Echo extends BaseHandler {
 
     @Override
     public void onReactorInit(Event event) {
+        // Every selectable is a possible source of future events. Our
+        // selectable stays alive until it reads the end of stream
+        // marker. This will keep the whole reactor running until we
+        // type Control-D.
         System.out.println("Type whatever you want and then use Control-D to exit:");
         Reactor reactor = event.getReactor();
         Selectable selectable = reactor.selectable();
-        selectable.setChannel(channel);
         setHandler(selectable, new EchoHandler());
         reactor.update(selectable);
     }

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GlobalLogger.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GlobalLogger.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GlobalLogger.java
index 1bb3d3e..ec56bd5 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GlobalLogger.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GlobalLogger.java
@@ -28,45 +28,6 @@ import org.apache.qpid.proton.engine.BaseHandler;
 import org.apache.qpid.proton.engine.Event;
 import org.apache.qpid.proton.reactor.Reactor;
 
-/*
-# Not every event goes to the reactor's event handler. If we have a
-# separate handler for something like a scheduled task, then those
-# events aren't logged by the logger associated with the reactor's
-# handler. Sometimes this is useful if you don't want to see them, but
-# sometimes you want the global picture.
-
-class Logger:
-
-    def on_unhandled(self, name, event):
-        print "LOG:", name, event
-
-class Task:
-
-    def on_timer_task(self, event):
-        print "Mission accomplished!"
-
-class Program:
-
-    def on_reactor_init(self, event):
-        print "Hello, World!"
-        event.reactor.schedule(0, Task())
-
-    def on_reactor_final(self, event):
-        print "Goodbye, World!"
-
-r = Reactor(Program())
-
-# In addition to having a regular handler, the reactor also has a
-# global handler that sees every event. By adding the Logger to the
-# global handler instead of the regular handler, we can log every
-# single event that occurs in the system regardless of whether or not
-# there are specific handlers associated with the objects that are the
-# target of those events.
-r.global_handler.add(Logger())
-r.run()
-
- */
-
 // Not every event goes to the reactor's event handler. If we have a
 // separate handler for something like a scheduled task, then those
 // events aren't logged by the logger associated with the reactor's

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GoodbyeWorld.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GoodbyeWorld.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GoodbyeWorld.java
index b04273b..6a69ba1 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GoodbyeWorld.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/GoodbyeWorld.java
@@ -28,13 +28,11 @@ import org.apache.qpid.proton.engine.BaseHandler;
 import org.apache.qpid.proton.engine.Event;
 import org.apache.qpid.proton.reactor.Reactor;
 
-// TODO: sort out docs!
 // So far the reactive hello-world doesn't look too different from a
-// regular old non-reactive hello-world. The on_reactor_init method can
+// regular old non-reactive hello-world. The onReactorInit method can
 // be used roughly as a 'main' method would. A program that only uses
 // that one event, however, isn't going to be very reactive. By using
 // other events, we can write a fully reactive program.
-
 public class GoodbyeWorld extends BaseHandler {
 
     // As before we handle the reactor init event.
@@ -46,7 +44,7 @@ public class GoodbyeWorld extends BaseHandler {
     // In addition to an initial event, the reactor also produces an
     // event when it is about to exit. This may not behave much
     // differently than just putting the goodbye print statement inside
-    // on_reactor_init, but as we grow our program, this piece of it
+    // onReactorInit, but as we grow our program, this piece of it
     // will always be what happens last, and will always happen
     // regardless of what other paths the main logic of our program
     // might take.

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/HelloWorld.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/HelloWorld.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/HelloWorld.java
index 055d6df..39a36fb 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/HelloWorld.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/HelloWorld.java
@@ -28,7 +28,6 @@ import org.apache.qpid.proton.engine.BaseHandler;
 import org.apache.qpid.proton.engine.Event;
 import org.apache.qpid.proton.reactor.Reactor;
 
-// TODO: sort out docs!
 /*
  * The proton reactor provides a general purpose event processing
  * library for writing reactive programs. A reactive program is defined
@@ -49,7 +48,7 @@ public class HelloWorld extends BaseHandler {
     public static void main(String[] args) throws IOException {
 
         // When you construct a reactor, you can give it a handler that
-        // is used, by default.
+        // is used, by default, to receive events generated by the reactor.
         Reactor reactor = Proton.reactor(new HelloWorld());
 
         // When you call run, the reactor will process events. The reactor init

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/README.md
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/README.md
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/README.md
new file mode 100644
index 0000000..73fbb87
--- /dev/null
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/README.md
@@ -0,0 +1,31 @@
+The examples in this directory provide a basic introduction to the
+proton reactor API and are best viewed in the order presented below.
+
+The examples contain comments that explain things in a tutorial-style
+manner. At some point soon this content will be pulled out into a
+proper tutorial that references the relevant code snippets from these
+examples. Until then please bear with this clumsy style of
+presentation.
+
+This API is present in Java and Python as well.  Most of these examples will
+transliterate into C in a fairly straightforward way.
+
+  - HelloWorld.java
+  - GoodbyeWorld.java
+
+  - Scheduling.java
+  - Counter.java
+  - CountRandomly.java
+
+  - Unhandled.java
+  - ReactorLogger.java
+  - GlobalLogger.java
+  - Delegates.java
+
+  - Handlers.java
+
+  - Echo.java
+  - Cat.java
+
+  - Send.java
+  - Recv.java

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/ReactorLogger.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/ReactorLogger.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/ReactorLogger.java
index b4a8cba..31c7511 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/ReactorLogger.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/ReactorLogger.java
@@ -28,40 +28,6 @@ import org.apache.qpid.proton.engine.BaseHandler;
 import org.apache.qpid.proton.engine.Event;
 import org.apache.qpid.proton.reactor.Reactor;
 
-/*
-class Logger:
-
-    def on_unhandled(self, name, event):
-        print "LOG:", name, event
-
-class Program:
-
-    def on_reactor_init(self, event):
-        print "Hello, World!"
-
-    def on_reactor_final(self, event):
-        print "Goodbye, World!"
-
-# You can pass multiple handlers to a reactor when you construct it.
-# Each of these handlers will see every event the reactor sees. By
-# combining this with on_unhandled, you can log each event that goes
-# to the reactor.
-r = Reactor(Program(), Logger())
-r.run()
-
-# Note that if you wanted to add the logger later, you could also
-# write the above as below. All arguments to the reactor are just
-# added to the default handler for the reactor.
-
-def logging_enabled():
-    return False
-
-r = Reactor(Program())
-if logging_enabled():
-    r.handler.add(Logger())
-r.run()
-
- */
 public class ReactorLogger extends BaseHandler {
 
     public static class Logger extends BaseHandler {

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Recv.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Recv.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Recv.java
index a5c6291..96a348a 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Recv.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Recv.java
@@ -50,9 +50,9 @@ public class Recv extends BaseHandler {
             // There is an optional third argument to the Reactor.acceptor
             // call. Using it, we could supply a handler here that would
             // become the handler for all accepted connections. If we omit
-            // it, the reactor simply inherets all the connection events.
+            // it, the reactor simply inherits all the connection events.
         } catch(IOException ioException) {
-            ioException.printStackTrace();    // TODO: what is the right answer?
+            ioException.printStackTrace();
         }
     }
 

http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/14972594/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Scheduling.java
----------------------------------------------------------------------
diff --git a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Scheduling.java
b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Scheduling.java
index f304b74..3aed27a 100644
--- a/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Scheduling.java
+++ b/examples/java/reactor/src/main/java/org/apache/qpid/proton/example/reactor/Scheduling.java
@@ -37,7 +37,18 @@ public class Scheduling extends BaseHandler {
     public void onReactorInit(Event event) {
         startTime = System.currentTimeMillis();
         System.out.println("Hello, World!");
+
+        // We can schedule a task event for some point in the future.
+        // This will cause the reactor to stick around until it has a
+        // chance to process the event.
+
+        // The first argument is the delay. The second argument is the
+        // handler for the event. We are just using self for now, but
+        // we could pass in another object if we wanted.
         Task task = event.getReactor().schedule(1000, this);
+
+        // We can ignore the task if we want to, but we can also use it
+        // to pass stuff to the handler.
         task.attachments().set("key", String.class, "Yay");
     }
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message