diff --git a/akka-docs/intro/what-is-akka.rst b/akka-docs/intro/what-is-akka.rst index 9739f9a4bd..6cc7c591c0 100644 --- a/akka-docs/intro/what-is-akka.rst +++ b/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 -management. - -See :ref:`remote-actors-scala` and :ref:`remote-actors-java`. +For an overview of the remoting see :ref:`remoting` Transactors ----------- diff --git a/akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java b/akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java new file mode 100644 index 0000000000..8dd48aee4c --- /dev/null +++ b/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 + } +} diff --git a/akka-docs/java/index.rst b/akka-docs/java/index.rst index 041dd289a5..fbc94dbc61 100644 --- a/akka-docs/java/index.rst +++ b/akka-docs/java/index.rst @@ -15,4 +15,6 @@ Java API fault-tolerance dispatchers routing + remoting + serialization extending-akka diff --git a/akka-docs/java/remoting.rst b/akka-docs/java/remoting.rst new file mode 100644 index 0000000000..15eacc3f4c --- /dev/null +++ b/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 `_ + +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://@:/ + +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. \ No newline at end of file diff --git a/akka-docs/java/serialization.rst b/akka-docs/java/serialization.rst new file mode 100644 index 0000000000..3d30f62864 --- /dev/null +++ b/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 `_ \ No newline at end of file diff --git a/akka-docs/scala/index.rst b/akka-docs/scala/index.rst index 742dc04ea9..898a74f905 100644 --- a/akka-docs/scala/index.rst +++ b/akka-docs/scala/index.rst @@ -15,6 +15,8 @@ Scala API fault-tolerance dispatchers routing + remoting + serialization fsm testing extending-akka diff --git a/akka-docs/scala/remoting.rst b/akka-docs/scala/remoting.rst new file mode 100644 index 0000000000..78f7a598ad --- /dev/null +++ b/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 `_ + +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://@:/ + +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. \ No newline at end of file diff --git a/akka-docs/scala/serialization.rst b/akka-docs/scala/serialization.rst new file mode 100644 index 0000000000..0f7dce63b4 --- /dev/null +++ b/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 `_ \ No newline at end of file