Docs: Various improvements

(cherry picked from commit aad2c29c68a239b8f2512abc5e93d58ca4354a49)

akka-docs/java/actor-registry.rst

@@ -8,12 +8,12 @@ ActorRegistry: Finding Actors
 
 Actors can be looked up using the 'akka.actor.Actors.registry()' object. Through this registry you can look up actors by:
 
-* uuid com.eaio.uuid.UUID – this uses the ‘uuid’ field in the Actor class, returns the actor reference for the actor with specified uuid, if one exists, otherwise None
-* id string – this uses the ‘id’ field in the Actor class, which can be set by the user (default is the class name), returns all actor references to actors with specified id
-* parameterized type - returns a 'ActorRef[]' with all actors that are a subtype of this specific type
-* specific actor class - returns a 'ActorRef[]' with all actors of this exact class
+* uuid com.eaio.uuid.UUID – this uses the ``uuid`` field in the Actor class, returns the actor reference for the actor with specified uuid, if one exists, otherwise None
+* id string – this uses the ``id`` field in the Actor class, which can be set by the user (default is the class name), returns all actor references to actors with specified id
+* parameterized type - returns a ``ActorRef[]`` with all actors that are a subtype of this specific type
+* specific actor class - returns a ``ActorRef[]`` with all actors of this exact class
 
-Actors are automatically registered in the ActorRegistry when they are started and removed when they are stopped. But you can explicitly register and unregister ActorRef's if you need to using the 'register' and 'unregister' methods.
+Actors are automatically registered in the ActorRegistry when they are started and removed when they are stopped. But you can explicitly register and unregister ActorRef's if you need to using the ``register`` and ``unregister`` methods.
 
 Here is a summary of the API for finding actors:
 

akka-docs/java/dataflow.rst

@@ -1,6 +1,10 @@
 Dataflow Concurrency (Java)
 ===========================
 
+.. sidebar:: Contents
+
+   .. contents:: :local:
+
 Introduction
 ------------
 
@@ -13,6 +17,7 @@ Dataflow concurrency is deterministic. This means that it will always behave the
 The best way to learn how to program with dataflow variables is to read the fantastic book `Concepts, Techniques, and Models of Computer Programming <http://www.info.ucl.ac.be/%7Epvr/book.html>`_. By Peter Van Roy and Seif Haridi.
 
 The documentation is not as complete as it should be, something we will improve shortly. For now, besides above listed resources on dataflow concurrency, I recommend you to read the documentation for the GPars implementation, which is heavily influenced by the Akka implementation:
+
 * `<http://gpars.codehaus.org/Dataflow>`_
 * `<http://www.gpars.org/guide/guide/7.%20Dataflow%20Concurrency.html>`_
 

akka-docs/java/typed-actors.rst

@@ -54,8 +54,8 @@ Then you can create an Typed Actor out of it by creating it through the 'TypedAc
     (RegistrationService) TypedActor.newInstance(RegistrationService.class, RegistrationServiceImpl.class, 1000);
   // The last parameter defines the timeout for Future calls
 
-**Creating Typed Actors with non-default constructor**
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creating Typed Actors with non-default constructor
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To create a typed actor that takes constructor arguments use a variant of 'newInstance' or 'newRemoteInstance' that takes an instance of a 'TypedActorFactory' in which you can create the TypedActor in any way you like. If you use this method then make sure that no one can get a reference to the actor instance. Touching actor state directly is bypassing the whole actor dispatching mechanism and create race conditions which can lead to corrupt data.
 
@@ -193,3 +193,56 @@ Akka can help you in this regard. It allows you to turn on an option for seriali
   }
 
 This will make a deep clone (using Java serialization) of all parameters.
+
+Guice Integration
+-----------------
+
+All Typed Actors support dependency injection using `Guice <http://code.google.com/p/google-guice/>`_ annotations (such as ‘@Inject’ etc.).
+The ``TypedActorManager`` class understands Guice and will do the wiring for you.
+
+External Guice modules
+^^^^^^^^^^^^^^^^^^^^^^
+
+You can also plug in external Guice modules and have not-actors wired up as part of the configuration.
+Here is an example:
+
+.. code-block:: java
+
+  import static akka.config.Supervision.*;
+  import static akka.config.SupervisorConfig.*;
+
+  TypedActorConfigurator manager = new TypedActorConfigurator();
+
+  manager.configure(
+    new AllForOneStrategy(new Class[]{Exception.class}, 3, 1000),
+      new SuperviseTypedActor[] {
+        new SuperviseTypedActor(
+          Foo.class,
+          FooImpl.class,
+          temporary(),
+          1000),
+        new SuperviseTypedActor(
+          Bar.class,
+          BarImpl.class,
+          permanent(),
+          1000)
+    })
+  .addExternalGuiceModule(new AbstractModule() {
+    protected void configure() {
+      bind(Ext.class).to(ExtImpl.class).in(Scopes.SINGLETON);
+    }})
+  .configure()
+  .inject()
+  .supervise();
+
+Retrieve the external Guice dependency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The external dependency can be retrieved like this:
+
+.. code-block:: java
+
+  Ext ext = manager.getExternalDependency(Ext.class);
+
+
+

akka-docs/java/untyped-actors.rst

@@ -227,6 +227,27 @@ Here is an example:
 Reply to messages
 -----------------
 
+Reply using the channel
+^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to have a handle to an object to whom you can reply to the message, you can use the Channel abstraction.
+Simply call getContext().channel() and then you can forward that to others, store it away or otherwise until you want to reply,
+which you do by Channel.sendOneWay(msg)
+
+.. code-block:: java
+
+  public void onReceive(Object message) throws Exception {
+    if (message instanceof String) {
+      String msg = (String)message;
+      if (msg.equals("Hello") && getContext().getSenderFuture().isDefined()) {
+        // Reply to original sender of message using the channel
+        getContext().channel().sendOneWay(msg + " from " + getContext().getUuid());
+      }
+    }
+  }
+
+We recommend that you as first choice use the channel abstraction instead of the other ways described in the following sections.
+
 Reply using the 'replySafe' and 'replyUnsafe' methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -307,24 +328,6 @@ Here is an example of how it can be used:
     }
   }
 
-Reply using the channel
-^^^^^^^^^^^^^^^^^^^^^^^
-
-If you want to have a handle to an object to whom you can reply to the message, you can use the Channel abstraction.
-Simply call getContext().channel() and then you can forward that to others, store it away or otherwise until you want to reply,
-which you do by Channel.sendOneWay(msg)
-
-.. code-block:: java
-
-  public void onReceive(Object message) throws Exception {
-    if (message instanceof String) {
-      String msg = (String)message;
-      if (msg.equals("Hello") && getContext().getSenderFuture().isDefined()) {
-        // Reply to original sender of message using the channel
-        getContext().channel().sendOneWay(msg + " from " + getContext().getUuid());
-      }
-    }
-  }
 
 Summary of reply semantics and options
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^