document RemoteRouterConfig, see #1846

- fix Java API
- change to pass in Addresses so that validation happens earlier

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

@@ -5,10 +5,13 @@ package akka.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.AddressExtractor;
 import java.util.Arrays;
 
 public class RouterViaProgramExample {
@@ -67,6 +70,14 @@ public class RouterViaProgramExample {
     for (int i = 1; i <= 6; i++) {
       router3.tell(new ExampleActor.Message(i));
     }
+    
+    //#remoteRoutees
+    Address addr1 = new Address("akka", "remotesys", "otherhost", 1234);
+    Address addr2 = AddressExtractor.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 {

akka-docs/java/routing.rst

@@ -54,6 +54,18 @@ Once you have the router actor it is just to send messages to it as you would to
 
 The router will apply its behavior to the message it receives and forward it to the routees.
 
+Remotely Deploying Routees
+**************************
+
+In addition to being able to supply looked-up remote actors as routees, you can
+make the router deploy its created children on a set of remote hosts; this will
+be done in round-robin fashion. In order to do that, wrap the router
+configuration in a :class:`RemoteRouterConfig`, attaching the remote addresses of
+the nodes to deploy to. Naturally, this requires your to include the
+``akka-remote`` module on your classpath:
+
+.. includecode:: code/akka/docs/jrouting/RouterViaProgramExample.java#remoteRoutees
+
 How Routing is Designed within Akka
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^