DOC: Improved scheduler doc. Split into Java/Scala samples

akka-docs/common/index.rst

@@ -4,5 +4,4 @@ Common utilities
 .. toctree::
    :maxdepth: 2
 
-   scheduler
    duration

akka-docs/java/code/akka/docs/actor/SchedulerDocTest.scala

@@ -2,4 +2,4 @@ package akka.docs.actor
 
 import org.scalatest.junit.JUnitSuite
 
-class UntypedActorTest extends UntypedActorTestBase with JUnitSuite
+class SchedulerDocTest extends SchedulerDocTestBase with JUnitSuite

akka-docs/java/code/akka/docs/actor/SchedulerDocTestBase.java

@@ -0,0 +1,85 @@
+package akka.docs.actor;
+
+//#imports1
+import akka.actor.Props;
+import akka.util.Duration;
+import java.util.concurrent.TimeUnit;
+
+//#imports1
+
+//#imports2
+import akka.actor.UntypedActor;
+import akka.actor.UntypedActorFactory;
+import akka.actor.Cancellable;
+
+//#imports2
+
+import akka.actor.ActorRef;
+import akka.actor.ActorSystem;
+import akka.testkit.AkkaSpec;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import static org.junit.Assert.*;
+
+public class SchedulerDocTestBase {
+
+  ActorSystem system;
+  ActorRef testActor;
+
+  @Before
+  public void setUp() {
+    system = ActorSystem.create("MySystem", AkkaSpec.testConf());
+    testActor = system.actorOf(new Props().withCreator(MyUntypedActor.class));
+  }
+
+  @After
+  public void tearDown() {
+    system.shutdown();
+  }
+
+  @Test
+  public void scheduleOneOffTask() {
+    //#schedule-one-off-message
+    //Schedules to send the "foo"-message to the testActor after 50ms
+    system.scheduler().scheduleOnce(Duration.create(50, TimeUnit.MILLISECONDS), testActor, "foo");
+    //#schedule-one-off-message
+
+    //#schedule-one-off-thunk
+    //Schedules a Runnable to be executed (send the current time) to the testActor after 50ms
+    system.scheduler().scheduleOnce(Duration.create(50, TimeUnit.MILLISECONDS), new Runnable() {
+      @Override
+      public void run() {
+        testActor.tell(System.currentTimeMillis());
+      }
+    });
+    //#schedule-one-off-thunk
+  }
+
+  @Test
+  public void scheduleRecurringTask() {
+    //#schedule-recurring
+    ActorRef tickActor = system.actorOf(new Props().withCreator(new UntypedActorFactory() {
+      public UntypedActor create() {
+        return new UntypedActor() {
+          public void onReceive(Object message) {
+            if (message.equals("Tick")) {
+              // Do someting
+            }
+          }
+        };
+      }
+    }));
+
+    //This will schedule to send the Tick-message
+    //to the tickActor after 0ms repeating every 50ms
+    Cancellable cancellable = system.scheduler().schedule(Duration.Zero(), Duration.create(50, TimeUnit.MILLISECONDS),
+        tickActor, "Tick");
+
+    //This cancels further Ticks to be sent
+    cancellable.cancel();
+    //#schedule-recurring
+    system.stop(tickActor);
+  }
+}

akka-docs/java/code/akka/docs/actor/UntypedActorDocTest.scala

@@ -0,0 +1,5 @@
+package akka.docs.actor
+
+import org.scalatest.junit.JUnitSuite
+
+class UntypedActorDocTest extends UntypedActorDocTestBase with JUnitSuite

akka-docs/java/code/akka/docs/actor/UntypedActorDocTestBase.java

@@ -36,7 +36,7 @@ import java.util.concurrent.TimeUnit;
 
 import static org.junit.Assert.*;
 
-public class UntypedActorTestBase {
+public class UntypedActorDocTestBase {
 
   @Test
   public void systemActorOf() {

akka-docs/java/code/akka/docs/dispatcher/DispatcherDocTestBase.java

@@ -28,7 +28,7 @@ import com.typesafe.config.ConfigFactory;
 
 import akka.actor.ActorSystem;
 import akka.docs.actor.MyUntypedActor;
-import akka.docs.actor.UntypedActorTestBase.MyActor;
+import akka.docs.actor.UntypedActorDocTestBase.MyActor;
 import akka.testkit.AkkaSpec;
 
 public class DispatcherDocTestBase {

akka-docs/java/index.rst

@@ -9,6 +9,7 @@ Java API
    untyped-actors
    typed-actors
    logging
+   scheduler
    futures
    dataflow
    transactors

akka-docs/java/scheduler.rst

@@ -0,0 +1,53 @@
+
+.. _scheduler-java:
+
+##################
+ Scheduler (Java)
+##################
+
+Sometimes the need for making things happen in the future arises, and where do you go look then?
+Look no further than ``ActorSystem``! There you find the :meth:`scheduler` method that returns an instance
+of akka.actor.Scheduler, this instance is unique per ActorSystem and is used internally for scheduling things
+to happen at specific points in time. Please note that the scheduled tasks are executed by the default
+``MessageDispatcher`` of the ``ActorSystem``.
+
+You can schedule sending of messages to actors and execution of tasks (functions or Runnable).
+You will get a ``Cancellable`` back that you can call :meth:`cancel` on to cancel the execution of the
+scheduled operation.
+
+Some examples
+-------------
+
+.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java
+   :include: imports1,schedule-one-off-message
+
+.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java
+   :include: schedule-one-off-thunk
+
+.. includecode:: code/akka/docs/actor/SchedulerDocTestBase.java
+   :include: imports1,imports2,schedule-recurring
+
+From ``akka.actor.ActorSystem``
+-------------------------------
+
+.. includecode:: ../../akka-actor/src/main/scala/akka/actor/ActorSystem.scala
+   :include: scheduler
+
+
+The Scheduler interface
+-----------------------
+
+.. includecode:: ../../akka-actor/src/main/scala/akka/actor/Scheduler.scala
+   :include: scheduler
+
+The Cancellable interface
+-------------------------
+
+This allows you to ``cancel`` something that has been scheduled for execution.
+
+.. warning::
+  This does not abort the execution of the task, if it had already been started.
+
+.. includecode:: ../../akka-actor/src/main/scala/akka/actor/Scheduler.scala
+   :include: cancellable
+

akka-docs/java/untyped-actors.rst

@@ -42,7 +42,7 @@ Here is an example:
 Creating Actors with default constructor
 ----------------------------------------
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
    :include: imports,system-actorOf
 
 The call to :meth:`actorOf` returns an instance of ``ActorRef``. This is a handle to
@@ -85,7 +85,7 @@ which can lead to corrupt data.
 
 Here is an example:
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#creating-constructor
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-constructor
 
 This way of creating the Actor is also great for integrating with Dependency Injection (DI) frameworks like Guice or Spring.
 
@@ -95,7 +95,7 @@ Creating Actors with Props
 ``Props`` is a configuration object to specify additional things for the actor to
 be created, such as the ``MessageDispatcher``.
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#creating-props
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#creating-props
 
 
 UntypedActor API
@@ -119,7 +119,7 @@ In addition, it offers:
 The remaining visible methods are user-overridable life-cycle hooks which are
 described in the following:
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#lifecycle-callbacks
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#lifecycle-callbacks
 
 The implementations shown above are the defaults provided by the :class:`UntypedActor`
 class.
@@ -250,7 +250,7 @@ To complete the future with an exception you need send a Failure message to the
 This is not done automatically when an actor throws an exception while processing a
 message.
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java#reply-exception
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java#reply-exception
 
 If the actor does not complete the future, it will expire after the timeout period,
 specified as parameter to the ``ask`` method.
@@ -278,7 +278,7 @@ even if that entails waiting for it (but keep in mind that waiting inside an
 actor is prone to dead-locks, e.g. if obtaining the result depends on
 processing another message on this actor).
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
    :include: import-future,using-ask
 
 Forward message
@@ -379,7 +379,7 @@ If the ``PoisonPill`` was sent with ``ask``, the ``Future`` will be completed wi
 
 Use it like this:
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
    :include: import-actors,poison-pill
 
 .. _UntypedActor.HotSwap:
@@ -400,7 +400,7 @@ The hotswapped code is kept in a Stack which can be pushed and popped.
 
 To hotswap the Actor using ``getContext().become``:
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
    :include: import-procedure,hot-swap-actor
 
 The ``become`` method is useful for many different things, such as to implement
@@ -430,7 +430,7 @@ through regular supervisor semantics.
 
 Use it like this:
 
-.. includecode:: code/akka/docs/actor/UntypedActorTestBase.java
+.. includecode:: code/akka/docs/actor/UntypedActorDocTestBase.java
    :include: import-actors,kill
 
 Actors and exceptions

akka-docs/scala/actors.rst

@@ -40,7 +40,7 @@ along with the implementation of how the messages should be processed.
 
 Here is an example:
 
-.. includecode:: code/ActorDocSpec.scala
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala
    :include: imports1,my-actor
 
 Please note that the Akka Actor ``receive`` message loop is exhaustive, which is
@@ -53,7 +53,7 @@ thrown and the actor is restarted when an unknown message is received.
 Creating Actors with default constructor
 ----------------------------------------
 
-.. includecode:: code/ActorDocSpec.scala
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala
    :include: imports2,system-actorOf
 
 The call to :meth:`actorOf` returns an instance of ``ActorRef``. This is a handle to
@@ -70,7 +70,7 @@ how the supervisor hierarchy is arranged. When using the context the current act
 will be supervisor of the created child actor. When using the system it will be
 a top level actor, that is supervised by the system (internal guardian actor).
 
-.. includecode:: code/ActorDocSpec.scala#context-actorOf
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#context-actorOf
 
 Actors are automatically started asynchronously when created.
 When you create the ``Actor`` then it will automatically call the ``preStart``
@@ -92,7 +92,7 @@ a call-by-name block in which you can create the Actor in any way you like.
 
 Here is an example:
 
-.. includecode:: code/ActorDocSpec.scala#creating-constructor
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#creating-constructor
 
 
 Creating Actors with Props
@@ -101,7 +101,7 @@ Creating Actors with Props
 ``Props`` is a configuration object to specify additional things for the actor to
 be created, such as the ``MessageDispatcher``.
 
-.. includecode:: code/ActorDocSpec.scala#creating-props
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#creating-props
 
 
 Creating Actors using anonymous classes
@@ -109,7 +109,7 @@ Creating Actors using anonymous classes
 
 When spawning actors for specific sub-tasks from within an actor, it may be convenient to include the code to be executed directly in place, using an anonymous class.
 
-.. includecode:: code/ActorDocSpec.scala#anonymous-actor
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#anonymous-actor
 
 .. warning::
 
@@ -145,7 +145,7 @@ In addition, it offers:
 
 You can import the members in the :obj:`context` to avoid prefixing access with ``context.``
 
-.. includecode:: code/ActorDocSpec.scala#import-context
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#import-context
 
 The remaining visible methods are user-overridable life-cycle hooks which are
 described in the following::
@@ -290,7 +290,7 @@ To complete the future with an exception you need send a Failure message to the
 This is not done automatically when an actor throws an exception while processing a
 message.
 
-.. includecode:: code/ActorDocSpec.scala#reply-exception
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#reply-exception
 
 If the actor does not complete the future, it will expire after the timeout period,
 which is taken from one of the following locations in order of precedence:
@@ -339,7 +339,7 @@ type, it will throw the exception or a :class:`ClassCastException` (if you want
 to get :obj:`None` in the latter case, use :meth:`Future.asSilently[T]`). In
 case of a timeout, :obj:`None` is returned.
 
-.. includecode:: code/ActorDocSpec.scala#using-ask
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#using-ask
 
 Forward message
 ---------------
@@ -371,7 +371,7 @@ This method should return a ``PartialFunction``, e.g. a ‘match/case’ clause
 which the message can be matched against the different case clauses using Scala
 pattern matching. Here is an example:
 
-.. includecode:: code/ActorDocSpec.scala
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala
    :include: imports1,my-actor
 
 
@@ -401,7 +401,7 @@ received within a certain time. To receive this timeout you have to set the
 ``receiveTimeout`` property and declare a case handing the ReceiveTimeout
 object.
 
-.. includecode:: code/ActorDocSpec.scala#receive-timeout
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#receive-timeout
 
 
 Stopping actors
@@ -465,7 +465,7 @@ pushed and popped.
 
 To hotswap the Actor behavior using ``become``:
 
-.. includecode:: code/ActorDocSpec.scala#hot-swap-actor
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#hot-swap-actor
 
 The ``become`` method is useful for many different things, but a particular nice
 example of it is in example where it is used to implement a Finite State Machine
@@ -475,12 +475,12 @@ example of it is in example where it is used to implement a Finite State Machine
 
 Here is another little cute example of ``become`` and ``unbecome`` in action:
 
-.. includecode:: code/ActorDocSpec.scala#swapper
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#swapper
 
 Encoding Scala Actors nested receives without accidentally leaking memory
 -------------------------------------------------------------------------
 
-See this `Unnested receive example <http://github.com/jboner/akka/blob/master/akka/akka-docs/scala/code/UnnestedReceives.scala>`_.
+See this `Unnested receive example <http://github.com/jboner/akka/blob/master/akka/akka-docs/scala/code/akka/docs/actor/UnnestedReceives.scala>`_.
 
 
 Downgrade
@@ -556,4 +556,4 @@ A bit advanced but very useful way of defining a base message handler and then
 extend that, either through inheritance or delegation, is to use
 ``PartialFunction.orElse`` chaining.
 
-.. includecode:: code/ActorDocSpec.scala#receive-orElse
+.. includecode:: code/akka/docs/actor/ActorDocSpec.scala#receive-orElse

akka-docs/scala/code/akka/docs/actor/SchedulerDocSpec.scala

@@ -1,4 +1,4 @@
-package akka.scheduler.actor
+package akka.docs.actor
 
 //#imports1
 import akka.actor.Actor
@@ -10,7 +10,6 @@ import akka.util.duration._
 import org.scalatest.{ BeforeAndAfterAll, WordSpec }
 import org.scalatest.matchers.MustMatchers
 import akka.testkit._
-import akka.util.duration._
 
 class SchedulerDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
   "schedule a one-off task" in {
@@ -22,25 +21,12 @@ class SchedulerDocSpec extends AkkaSpec(Map("akka.loglevel" -> "INFO")) {
     expectMsg(1 second, "foo")
 
     //#schedule-one-off-thunk
-    //Schedules to send the "foo"-message to the testActor after 50ms
+    //Schedules a function to be executed (send the current time) to the testActor after 50ms
     system.scheduler.scheduleOnce(50 milliseconds) {
-      testActor ! "foo"
+      testActor ! System.currentTimeMillis
     }
     //#schedule-one-off-thunk
 
-    expectMsg(1 second, "foo")
-
-    //#schedule-one-off-runnable
-    //Schedules to send the "foo"-message to the testActor after 50ms
-    system.scheduler.scheduleOnce(
-      50 milliseconds,
-      new Runnable {
-        def run = testActor ! "foo"
-      })
-
-    //#schedule-one-off-runnable
-
-    expectMsg(1 second, "foo")
   }
 
   "schedule a recurring task" in {

akka-docs/scala/index.rst

@@ -9,6 +9,7 @@ Scala API
    actors
    typed-actors
    logging
+   scheduler
    futures
    dataflow
    agents

akka-docs/scala/scheduler.rst

@@ -1,30 +1,31 @@
-Scheduler
+
-=========
+.. _scheduler-scala:
+
+###################
+ Scheduler (Scala)
+###################
 
 Sometimes the need for making things happen in the future arises, and where do you go look then?
-Look no further than ``ActorSystem``! There you find the :meth:``scheduler`` method that returns an instance
+Look no further than ``ActorSystem``! There you find the :meth:`scheduler` method that returns an instance
 of akka.actor.Scheduler, this instance is unique per ActorSystem and is used internally for scheduling things
 to happen at specific points in time. Please note that the scheduled tasks are executed by the default
 ``MessageDispatcher`` of the ``ActorSystem``.
 
 You can schedule sending of messages to actors and execution of tasks (functions or Runnable).
-You will get a ``Cancellable`` back that you can call :meth:``cancel`` on to cancel the execution of the
+You will get a ``Cancellable`` back that you can call :meth:`cancel` on to cancel the execution of the
 scheduled operation.
 
 Some examples
 -------------
 
-.. includecode:: code/SchedulerDocSpec.scala
+.. includecode:: code/akka/docs/actor/SchedulerDocSpec.scala
    :include: imports1,schedule-one-off-message
 
-.. includecode:: code/SchedulerDocSpec.scala
+.. includecode:: code/akka/docs/actor/SchedulerDocSpec.scala
-   :include: imports1,schedule-one-off-thunk
+   :include: schedule-one-off-thunk
 
-.. includecode:: code/SchedulerDocSpec.scala
+.. includecode:: code/akka/docs/actor/SchedulerDocSpec.scala
-   :include: imports1,schedule-one-off-runnable
+   :include: schedule-recurring
-
-.. includecode:: code/SchedulerDocSpec.scala
-   :include: imports1,schedule-recurring
 
 From ``akka.actor.ActorSystem``
 -------------------------------