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

Initial stab at remoting documentation. See #1175

akka-docs/intro/what-is-akka.rst

@@ -50,13 +50,12 @@ provide truly fault-tolerant systems.
 
 See :ref:`fault-tolerance-scala` and :ref:`fault-tolerance-java`
 
-Remote Actors
+Location Transparency
--------------
+---------------------
+Everything in Akka is designed to work in a distributed environment: all
+interactions of actors use purely message passing and everything is asynchronous.
 
-Highly performant distributed actors with remote supervision and error
+For an overview of the remoting see :ref:`remoting`
-management.
-
-See :ref:`remote-actors-scala` and :ref:`remote-actors-java`.
 
 Transactors
 -----------

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>`_

akka-docs/scala/index.rst

@@ -15,6 +15,8 @@ Scala API
    fault-tolerance
    dispatchers
    routing
+   remoting
+   serialization
    fsm
    testing
    extending-akka

akka-docs/scala/remoting.rst

@@ -0,0 +1,107 @@
+
+.. _remoting-scala:
+
+#################
+ Remoting (Scala)
+#################
+
+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
+
+In you SBT project you should add the following as a dependency::
+
+  "com.typesafe.akka" % "akka-remote" % "2.0-SNAPSHOT"
+
+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::
+
+  val actor = context.actorFor("/serviceA/retrieval")
+
+This will obtain an ``ActorRef`` on a remote node::
+
+  val actor = context.actorFor("akka://app@10.0.0.1:2552/user/serviceA/retrieval")
+
+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-scala`
+
+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/scala/serialization.rst

@@ -0,0 +1,12 @@
+
+.. _serialization-scala:
+
+######################
+ Serialization (Scala)
+######################
+
+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>`_