Move all doc examples out of the akka-package to avoid use of private APIs. See #2092

akka-docs/java/code/docs/jrouting/CustomRouterDocTest.scala

@@ -0,0 +1,5 @@
+package docs.jrouting;
+
+import org.scalatest.junit.JUnitSuite
+
+class CustomRouterDocTest extends CustomRouterDocTestBase with JUnitSuite

akka-docs/java/code/docs/jrouting/CustomRouterDocTestBase.java

@@ -0,0 +1,177 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import java.util.List;
+import java.util.Arrays;
+
+import org.junit.After;
+import org.junit.Before;
+import org.junit.Test;
+import static org.junit.Assert.assertEquals;
+
+import akka.actor.*;
+import akka.routing.*;
+import akka.util.Duration;
+import akka.util.Timeout;
+import akka.dispatch.Await;
+import akka.dispatch.Future;
+import akka.dispatch.Dispatchers;
+import akka.testkit.AkkaSpec;
+import com.typesafe.config.ConfigFactory;
+import static akka.pattern.Patterns.ask;
+
+import static docs.jrouting.CustomRouterDocTestBase.DemocratActor;
+import static docs.jrouting.CustomRouterDocTestBase.RepublicanActor;
+import static docs.jrouting.CustomRouterDocTestBase.Message.*;
+
+public class CustomRouterDocTestBase {
+
+  ActorSystem system;
+
+  @Before
+  public void setUp() {
+    system = ActorSystem.create("MySystem", AkkaSpec.testConf());
+  }
+
+  @After
+  public void tearDown() {
+    system.shutdown();
+  }
+  
+  public static class MyActor extends UntypedActor {
+    @Override public void onReceive(Object o) {}
+  }
+  
+  @Test
+  public void demonstrateDispatchers() {
+    //#dispatchers
+    final ActorRef router = system.actorOf(new Props(MyActor.class)
+      .withRouter(new RoundRobinRouter(5).withDispatcher("head")) // “head” router runs on "head" dispatcher
+      .withDispatcher("workers")); // MyActor “workers” run on "workers" dispatcher
+    //#dispatchers
+  }
+  
+  @Test
+  public void demonstrateSupervisor() {
+    //#supervision
+    final SupervisorStrategy strategy = new OneForOneStrategy(5, Duration.parse("1 minute"),
+        new Class<?>[] { Exception.class });
+    final ActorRef router = system.actorOf(new Props(MyActor.class)
+        .withRouter(new RoundRobinRouter(5).withSupervisorStrategy(strategy)));
+    //#supervision
+  }
+
+  //#crTest
+  @Test
+  public void countVotesAsIntendedNotAsInFlorida() throws Exception {
+    ActorRef routedActor = system.actorOf(new Props().withRouter(new VoteCountRouter()));
+    routedActor.tell(DemocratVote);
+    routedActor.tell(DemocratVote);
+    routedActor.tell(RepublicanVote);
+    routedActor.tell(DemocratVote);
+    routedActor.tell(RepublicanVote);
+    Timeout timeout = new Timeout(Duration.parse("1 seconds"));
+    Future<Object> democratsResult = ask(routedActor, DemocratCountResult, timeout);
+    Future<Object> republicansResult = ask(routedActor, RepublicanCountResult, timeout);
+
+    assertEquals(3, Await.result(democratsResult, timeout.duration()));
+    assertEquals(2, Await.result(republicansResult, timeout.duration()));
+  }
+
+  //#crTest
+
+  //#CustomRouter
+  //#crMessages
+  enum Message {
+    DemocratVote, DemocratCountResult, RepublicanVote, RepublicanCountResult
+  }
+
+  //#crMessages
+
+  //#crActors
+  public static class DemocratActor extends UntypedActor {
+    int counter = 0;
+
+    public void onReceive(Object msg) {
+      switch ((Message) msg) {
+      case DemocratVote:
+        counter++;
+        break;
+      case DemocratCountResult:
+        getSender().tell(counter, getSelf());
+        break;
+      default:
+        unhandled(msg);
+      }
+    }
+  }
+
+  public static class RepublicanActor extends UntypedActor {
+    int counter = 0;
+
+    public void onReceive(Object msg) {
+      switch ((Message) msg) {
+      case RepublicanVote:
+        counter++;
+        break;
+      case RepublicanCountResult:
+        getSender().tell(counter, getSelf());
+        break;
+      default:
+        unhandled(msg);
+      }
+    }
+  }
+
+  //#crActors
+
+  //#crRouter
+  public static class VoteCountRouter extends CustomRouterConfig {
+    
+    @Override public String routerDispatcher() {
+      return Dispatchers.DefaultDispatcherId();
+    }
+    
+    @Override public SupervisorStrategy supervisorStrategy() {
+      return SupervisorStrategy.defaultStrategy();
+    }
+
+    //#crRoute
+    @Override
+    public CustomRoute createCustomRoute(Props props, RouteeProvider routeeProvider) {
+      final ActorRef democratActor = routeeProvider.context().actorOf(new Props(DemocratActor.class), "d");
+      final ActorRef republicanActor = routeeProvider.context().actorOf(new Props(RepublicanActor.class), "r");
+      List<ActorRef> routees = Arrays.asList(new ActorRef[] { democratActor, republicanActor });
+
+      //#crRegisterRoutees
+      routeeProvider.registerRoutees(routees);
+      //#crRegisterRoutees
+
+      //#crRoutingLogic
+      return new CustomRoute() {
+        @Override
+        public Iterable<Destination> destinationsFor(ActorRef sender, Object msg) {
+          switch ((Message) msg) {
+          case DemocratVote:
+          case DemocratCountResult:
+            return Arrays.asList(new Destination[] { new Destination(sender, democratActor) });
+          case RepublicanVote:
+          case RepublicanCountResult:
+            return Arrays.asList(new Destination[] { new Destination(sender, republicanActor) });
+          default:
+            throw new IllegalArgumentException("Unknown message: " + msg);
+          }
+        }
+      };
+      //#crRoutingLogic
+    }
+    //#crRoute
+
+  }
+
+  //#crRouter
+  //#CustomRouter
+
+}

akka-docs/java/code/docs/jrouting/FibonacciActor.java

@@ -0,0 +1,48 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import java.io.Serializable;
+
+import akka.actor.UntypedActor;
+
+//#fibonacciActor
+public class FibonacciActor extends UntypedActor {
+  public void onReceive(Object msg) {
+    if (msg instanceof FibonacciNumber) {
+      FibonacciNumber fibonacciNumber = (FibonacciNumber) msg;
+      getSender().tell(fibonacci(fibonacciNumber.getNbr()));
+    } else {
+      unhandled(msg);
+    }
+  }
+
+  private int fibonacci(int n) {
+    return fib(n, 1, 0);
+  }
+
+  private int fib(int n, int b, int a) {
+    if (n == 0)
+      return a;
+    // recursion
+    return fib(n - 1, a + b, b);
+  }
+
+  public static class FibonacciNumber implements Serializable {
+    private static final long serialVersionUID = 1L;
+    private final int nbr;
+
+    public FibonacciNumber(int nbr) {
+      this.nbr = nbr;
+    }
+
+    public int getNbr() {
+      return nbr;
+    }
+
+  }
+}
+
+//#fibonacciActor
+

akka-docs/java/code/docs/jrouting/ParentActor.java

@@ -0,0 +1,69 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import akka.routing.ScatterGatherFirstCompletedRouter;
+import akka.routing.BroadcastRouter;
+import akka.routing.RandomRouter;
+import akka.routing.RoundRobinRouter;
+import akka.routing.SmallestMailboxRouter;
+import akka.actor.UntypedActor;
+import akka.actor.ActorRef;
+import akka.actor.Props;
+import akka.util.Duration;
+import akka.util.Timeout;
+import akka.dispatch.Future;
+import akka.dispatch.Await;
+
+//#parentActor
+public class ParentActor extends UntypedActor {
+  public void onReceive(Object msg) throws Exception {
+    if (msg.equals("rrr")) {
+      //#roundRobinRouter
+      ActorRef roundRobinRouter = getContext().actorOf(
+          new Props(PrintlnActor.class).withRouter(new RoundRobinRouter(5)), "router");
+      for (int i = 1; i <= 10; i++) {
+        roundRobinRouter.tell(i, getSelf());
+      }
+      //#roundRobinRouter
+    } else if (msg.equals("rr")) {
+      //#randomRouter
+      ActorRef randomRouter = getContext().actorOf(new Props(PrintlnActor.class).withRouter(new RandomRouter(5)),
+          "router");
+      for (int i = 1; i <= 10; i++) {
+        randomRouter.tell(i, getSelf());
+      }
+      //#randomRouter
+    } else if (msg.equals("smr")) {
+      //#smallestMailboxRouter
+      ActorRef smallestMailboxRouter = getContext().actorOf(
+          new Props(PrintlnActor.class).withRouter(new SmallestMailboxRouter(5)), "router");
+      for (int i = 1; i <= 10; i++) {
+        smallestMailboxRouter.tell(i, getSelf());
+      }
+      //#smallestMailboxRouter
+    } else if (msg.equals("br")) {
+      //#broadcastRouter
+      ActorRef broadcastRouter = getContext().actorOf(new Props(PrintlnActor.class).withRouter(new BroadcastRouter(5)),
+          "router");
+      broadcastRouter.tell("this is a broadcast message", getSelf());
+      //#broadcastRouter
+    } else if (msg.equals("sgfcr")) {
+      //#scatterGatherFirstCompletedRouter
+      ActorRef scatterGatherFirstCompletedRouter = getContext().actorOf(
+          new Props(FibonacciActor.class).withRouter(new ScatterGatherFirstCompletedRouter(5, Duration
+              .parse("2 seconds"))), "router");
+      Timeout timeout = new Timeout(Duration.parse("5 seconds"));
+      Future<Object> futureResult = akka.pattern.Patterns.ask(scatterGatherFirstCompletedRouter,
+          new FibonacciActor.FibonacciNumber(10), timeout);
+      int result = (Integer) Await.result(futureResult, timeout.duration());
+      //#scatterGatherFirstCompletedRouter
+      System.out.println(String.format("The result of calculating Fibonacci for 10 is %d", result));
+    } else {
+      unhandled(msg);
+    }
+  }
+}
+
+//#parentActor

akka-docs/java/code/docs/jrouting/PrintlnActor.java

@@ -0,0 +1,15 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import akka.actor.UntypedActor;
+
+//#printlnActor
+public class PrintlnActor extends UntypedActor {
+  public void onReceive(Object msg) {
+    System.out.println(String.format("Received message '%s' in actor %s", msg, getSelf().path().name()));
+  }
+}
+
+//#printlnActor

akka-docs/java/code/docs/jrouting/RouterViaConfigExample.java

@@ -0,0 +1,58 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import akka.routing.FromConfig;
+import akka.actor.ActorRef;
+import akka.actor.Props;
+import akka.actor.UntypedActor;
+import akka.actor.ActorSystem;
+import com.typesafe.config.ConfigFactory;
+import com.typesafe.config.Config;
+
+public class RouterViaConfigExample {
+
+  public static class ExampleActor extends UntypedActor {
+    public void onReceive(Object msg) {
+      if (msg instanceof Message) {
+        Message message = (Message) msg;
+        System.out.println(String.format("Received %s in router %s", message.getNbr(), getSelf().path().name()));
+      } else {
+        unhandled(msg);
+      }
+    }
+
+    public static class Message {
+      private final int nbr;
+
+      public Message(int nbr) {
+        this.nbr = nbr;
+      }
+
+      public int getNbr() {
+        return nbr;
+      }
+
+    }
+  }
+
+  public static void main(String... args) {
+    Config config = ConfigFactory.parseString("akka.actor.deployment {\n" + "  /router {\n"
+        + "    router = round-robin\n" + "    nr-of-instances = 5\n" + "  }\n" + "}\n");
+    ActorSystem system = ActorSystem.create("Example", config);
+    //#configurableRouting
+    ActorRef router = system.actorOf(new Props(ExampleActor.class).withRouter(new FromConfig()), "router");
+    //#configurableRouting
+    for (int i = 1; i <= 10; i++) {
+      router.tell(new ExampleActor.Message(i));
+    }
+
+    //#configurableRoutingWithResizer
+    ActorRef router2 = system.actorOf(new Props(ExampleActor.class).withRouter(new FromConfig()), "router2");
+    //#configurableRoutingWithResizer
+    for (int i = 1; i <= 10; i++) {
+      router2.tell(new ExampleActor.Message(i));
+    }
+  }
+}

akka-docs/java/code/docs/jrouting/RouterViaProgramExample.java

@@ -0,0 +1,96 @@
+/**
+ * Copyright (C) 2009-2012 Typesafe Inc. <http://www.typesafe.com>
+ */
+package docs.jrouting;
+
+import akka.routing.RoundRobinRouter;
+import akka.routing.DefaultResizer;
+import akka.routing.RemoteRouterConfig;
+import akka.actor.ActorRef;
+import akka.actor.Props;
+import akka.actor.UntypedActor;
+import akka.actor.ActorSystem;
+import akka.actor.Address;
+import akka.actor.AddressFromURIString;
+import java.util.Arrays;
+
+public class RouterViaProgramExample {
+
+  public static class ExampleActor extends UntypedActor {
+    public void onReceive(Object msg) {
+      if (msg instanceof Message) {
+        Message message = (Message) msg;
+        System.out.println(String.format("Received %s in router %s", message.getNbr(), getSelf().path().name()));
+      } else {
+        unhandled(msg);
+      }
+    }
+
+    public static class Message {
+      private final int nbr;
+
+      public Message(int nbr) {
+        this.nbr = nbr;
+      }
+
+      public int getNbr() {
+        return nbr;
+      }
+
+    }
+  }
+
+  public static void main(String... args) {
+    ActorSystem system = ActorSystem.create("RPE");
+    //#programmaticRoutingNrOfInstances
+    int nrOfInstances = 5;
+    ActorRef router1 = system.actorOf(new Props(ExampleActor.class).withRouter(new RoundRobinRouter(nrOfInstances)));
+    //#programmaticRoutingNrOfInstances
+    for (int i = 1; i <= 6; i++) {
+      router1.tell(new ExampleActor.Message(i));
+    }
+
+    //#programmaticRoutingRoutees
+    ActorRef actor1 = system.actorOf(new Props(ExampleActor.class));
+    ActorRef actor2 = system.actorOf(new Props(ExampleActor.class));
+    ActorRef actor3 = system.actorOf(new Props(ExampleActor.class));
+    Iterable<ActorRef> routees = Arrays.asList(new ActorRef[] { actor1, actor2, actor3 });
+    ActorRef router2 = system.actorOf(new Props(ExampleActor.class).withRouter(RoundRobinRouter.create(routees)));
+    //#programmaticRoutingRoutees
+    for (int i = 1; i <= 6; i++) {
+      router2.tell(new ExampleActor.Message(i));
+    }
+
+    //#programmaticRoutingWithResizer
+    int lowerBound = 2;
+    int upperBound = 15;
+    DefaultResizer resizer = new DefaultResizer(lowerBound, upperBound);
+    ActorRef router3 = system.actorOf(new Props(ExampleActor.class).withRouter(new RoundRobinRouter(nrOfInstances)));
+    //#programmaticRoutingWithResizer
+    for (int i = 1; i <= 6; i++) {
+      router3.tell(new ExampleActor.Message(i));
+    }
+    
+    //#remoteRoutees
+    Address addr1 = new Address("akka", "remotesys", "otherhost", 1234);
+    Address addr2 = AddressFromURIString.parse("akka://othersys@anotherhost:1234");
+    Address[] addresses = new Address[] { addr1, addr2 };
+    ActorRef routerRemote = system.actorOf(new Props(ExampleActor.class)
+      .withRouter(new RemoteRouterConfig(new RoundRobinRouter(5), addresses)));
+    //#remoteRoutees
+  }
+  
+  private class CompileCheckJavaDocsForRouting extends UntypedActor {
+
+    @Override
+    public void onReceive(Object o) {
+      //#reply-with-parent
+      getSender().tell("reply", getContext().parent()); // replies go to router
+      //#reply-with-parent
+      //#reply-with-self
+      getSender().tell("reply", getSelf()); // replies go to this actor
+      //#reply-with-self
+    }
+    
+  }
+}