make supervisorStrategy of Router configurable, see #1835

- also do not scrap router’s children upon restart
- and add docs and tests

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

@@ -52,6 +52,16 @@ public class CustomRouterDocTestBase {
       .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<? extends Throwable>[] { Exception });
+    final ActorRef router = system.actorOf(new Props(MyActor.class)
+        .withRouter(new RoundRobinRouter(5).withSupervisorStrategy(strategy)));
+    //#supervision
+  }
 
   //#crTest
   @Test
@@ -123,6 +133,10 @@ public class CustomRouterDocTestBase {
     @Override public String routerDispatcher() {
       return Dispatchers.DefaultDispatcherId();
     }
+    
+    @Override public SupervisorStrategy supervisorStrategy() {
+      return SupervisorStrategy.defaultStrategy();
+    }
 
     //#crRoute
     @Override

akka-docs/java/routing.rst

@@ -92,6 +92,29 @@ to the actor hierarchy, changing the actor paths of all children of the router.
 The routees especially do need to know that they are routed to in order to
 choose the sender reference for any messages they dispatch as shown above.
 
+Routers vs. Supervision
+^^^^^^^^^^^^^^^^^^^^^^^
+
+As explained in the previous section, routers create new actor instances as
+children of the “head” router, who therefor also is their supervisor. The
+supervisor strategy of this actor can be configured by means of the
+:meth:`RouterConfig.supervisorStrategy` property, which is supported for all
+built-in router types. It defaults to “always escalate”, which leads to the
+application of the router’s parent’s supervision directive to all children of
+the router uniformly (i.e. not only the one which failed). It should be
+mentioned that the router overrides the default behavior of terminating all
+children upon restart, which means that a restart—while re-creating them—does
+not have an effect on the number of actors in the pool.
+
+Setting the strategy is easily done:
+
+.. includecode:: code/akka/docs/jrouting/CustomRouterDocTestBase.java
+   :include: supervision
+
+Another potentially useful approach is to give the router the same strategy as
+its parent, which effectively treats all actors in the pool as if they were
+direct children of their grand-parent instead.
+
 Router usage
 ^^^^^^^^^^^^