Merge pull request #168 from jboner/1175-docs-remoting-he

Initial stab at remoting documentation. See #1175

akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java

@@ -0,0 +1,18 @@
+package akka.docs.remoting;
+
+import akka.actor.ActorRef;
+import akka.actor.UntypedActor;
+
+public class RemoteActorExample extends UntypedActor {
+    //#localNodeActor
+    ActorRef a1 = getContext().actorFor("/serviceA/retrieval");
+    //#localNodeActor
+
+    //#remoteNodeActor
+    ActorRef a2 = getContext().actorFor("akka://app@10.0.0.1:2552/user/serviceA/retrieval");
+    //#remoteNodeActor
+
+    public void onReceive(Object message) throws Exception {
+        // Do something
+    }
+}

akka-docs/java/index.rst

@@ -15,4 +15,6 @@ Java API
    fault-tolerance
    dispatchers
    routing
+   remoting
+   serialization
    extending-akka

akka-docs/java/remoting.rst

@@ -0,0 +1,103 @@
+
+.. _remoting-java:
+
+#####################
+ Remoting (Java)
+#####################
+
+For an introduction of remoting capabilities of Akka please see :ref:`remoting`.
+
+Preparing your ActorSystem for Remoting
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Akka remoting is a separate jar file. Make sure that you have a dependency from your project to this jar::
+
+  akka-remote.jar
+
+First of all you have to change the actor provider from ``LocalActorRefProvider`` to ``RemoteActorRefProvider``::
+
+  akka {
+    actor {
+     provider = "akka.remote.RemoteActorRefProvider"
+    }
+  }
+
+After that you must also add the following settings::
+
+  akka {
+    server {
+      # The hostname or ip to bind the remoting to,
+      # InetAddress.getLocalHost.getHostAddress is used if empty
+      hostname = ""
+
+      # The default remote server port clients should connect to.
+      # Default is 2552 (AKKA)
+      port = 2552
+    }
+  }
+
+These are the bare minimal settings that must exist in order to get started with remoting.
+There are, of course, more properties that can be tweaked. We refer to the following
+reference file for more information:
+
+* `reference.conf of akka-remote <https://github.com/jboner/akka/blob/master/akka-remote/src/main/resources/reference.conf#L39>`_
+
+Using Remote Actors
+^^^^^^^^^^^^^^^^^^^
+
+The configuration below instructs the system to deploy the actor "retrieval” on the specific host "app@10.0.0.1".
+The "app" in this case refers to the name of the ``ActorSystem``::
+
+  akka {
+    actor {
+      deployment {
+        /serviceA/retrieval {
+          remote = “akka://app@10.0.0.1:2552”
+        }
+      }
+    }
+  }
+
+Logical path lookup is supported on the node you are on, i.e. to use the
+actor created above you would do the following:
+
+.. includecode:: code/akka/docs/remoting/RemoteActorExample.java#localNodeActor
+
+This will obtain an ``ActorRef`` on a remote node:
+
+.. includecode:: code/akka/docs/remoting/RemoteActorExample.java#remoteNodeActor
+
+As you can see from the example above the following pattern is used to find an ``ActorRef`` on a remote node::
+
+    akka://<actorsystemname>@<hostname>:<port>/<actor path>
+
+Serialization
+^^^^^^^^^^^^^
+
+When using remoting for actors you must ensure that the ``props`` and ``messages`` used for
+those actors are serializable. Failing to do so will cause the system to behave in an unintended way.
+
+For more information please see :ref:`serialization-java`
+
+Routers with Remote Destinations
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is absolutely feasible to combine remoting with :ref:`routers`.
+This is also done via configuration::
+
+  akka {
+    actor {
+      deployment {
+        /serviceA/aggregation {
+          router = “round-robin”
+          nr-of-instances = 10
+          target {
+            nodes = [“akka://app@10.0.0.2:2552”, “akka://app@10.0.0.3:2552”]
+          }
+        }
+      }
+    }
+  }
+
+This configuration setting will clone the actor “aggregation” 10 times and deploy it evenly distributed across
+the two given target nodes.

akka-docs/java/serialization.rst

@@ -0,0 +1,12 @@
+
+.. _serialization-java:
+
+#####################
+ Serialization (Java)
+#####################
+
+Serialization will soon be documented.
+
+Until then we refer to the following section in the configuration file:
+
+* `Serializers <https://github.com/jboner/akka/blob/master/akka-actor/src/main/resources/reference.conf#L180>`_