document RemoteRouterConfig, see #1846

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

akka-docs/scala/code/akka/docs/routing/RouterViaProgramExample.scala

@@ -6,6 +6,7 @@ package akka.docs.routing
 import akka.routing.RoundRobinRouter
 import akka.actor.{ ActorRef, Props, Actor, ActorSystem }
 import akka.routing.DefaultResizer
+import akka.routing.RemoteRouterConfig
 
 case class Message1(nbr: Int)
 
@@ -40,4 +41,13 @@ object RoutingProgrammaticallyExample extends App {
   //#programmaticRoutingWithResizer
   1 to 6 foreach { i ⇒ router3 ! Message1(i) }
 
+  //#remoteRoutees
+  import akka.actor.{ Address, AddressExtractor }
+  val addresses = Seq(
+    Address("akka", "remotesys", "otherhost", 1234),
+    AddressExtractor("akka://othersys@anotherhost:1234"))
+  val routerRemote = system.actorOf(Props[ExampleActor1].withRouter(
+    RemoteRouterConfig(RoundRobinRouter(5), addresses)))
+  //#remoteRoutees
+
 }

akka-docs/scala/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/routing/RouterViaProgramExample.scala#remoteRoutees
+
 How Routing is Designed within Akka
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^