clarify need to carefully managing blocking, see #2616

akka-docs/rst/java/code/docs/dispatcher/DispatcherDocTestBase.java

@@ -5,10 +5,6 @@ package docs.dispatcher;
 
 //#imports
 import akka.actor.*;
-import akka.actor.ActorRef;
-import akka.actor.Props;
-import akka.actor.UntypedActor;
-import akka.actor.UntypedActorFactory;
 //#imports
 
 //#imports-prio
@@ -37,6 +33,7 @@ import org.junit.After;
 import org.junit.Before;
 import org.junit.Test;
 import scala.Option;
+import scala.concurrent.ExecutionContext;
 
 import com.typesafe.config.ConfigFactory;
 
@@ -75,6 +72,14 @@ public class DispatcherDocTestBase {
         .withDispatcher("my-pinned-dispatcher"));
     //#defining-pinned-dispatcher
   }
+  
+  public void compileLookup() {
+    //#lookup
+    // this is scala.concurrent.ExecutionContext
+    // for use with Futures, Scheduler, etc.
+    final ExecutionContext ex = system.dispatchers().lookup("my-dispatcher");
+    //#lookup
+  }
 
   @Test
   public void priorityDispatcher() throws Exception {

akka-docs/rst/java/dispatchers.rst

@@ -13,6 +13,15 @@ Default dispatcher
 Every ``ActorSystem`` will have a default dispatcher that will be used in case nothing else is configured for an ``Actor``.
 The default dispatcher can be configured, and is by default a ``Dispatcher`` with a "fork-join-executor", which gives excellent performance in most cases.
 
+.. _dispatcher-lookup-java:
+
+Looking up a Dispatcher
+-----------------------
+
+Dispatchers implement the :class:`ExecutionContext` interface and can thus be used to run :class:`Future` invocations etc.
+
+.. includecode:: code/docs/dispatcher/DispatcherDocTestBase.java#lookup
+
 Setting the dispatcher for an Actor
 -----------------------------------