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

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