From 94017d8b7a8982a27cc977d3e61199b182902ccc Mon Sep 17 00:00:00 2001 From: Henrik Engstrom Date: Thu, 15 Dec 2011 18:05:24 +0100 Subject: [PATCH 1/3] Initial stab at remoting documentation. See #1175 --- akka-docs/intro/what-is-akka.rst | 11 ++--- akka-docs/java/index.rst | 1 + akka-docs/java/remoting.rst | 8 +++ akka-docs/scala/index.rst | 1 + akka-docs/scala/remoting.rst | 84 ++++++++++++++++++++++++++++++++ 5 files changed, 99 insertions(+), 6 deletions(-) create mode 100644 akka-docs/java/remoting.rst create mode 100644 akka-docs/scala/remoting.rst diff --git a/akka-docs/intro/what-is-akka.rst b/akka-docs/intro/what-is-akka.rst index 9739f9a4bd..0041a41fde 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 -------------- +Transparent Remoting +-------------------- +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/index.rst b/akka-docs/java/index.rst index 041dd289a5..5f886c9bd6 100644 --- a/akka-docs/java/index.rst +++ b/akka-docs/java/index.rst @@ -15,4 +15,5 @@ Java API fault-tolerance dispatchers routing + remoting extending-akka diff --git a/akka-docs/java/remoting.rst b/akka-docs/java/remoting.rst new file mode 100644 index 0000000000..9a47790b99 --- /dev/null +++ b/akka-docs/java/remoting.rst @@ -0,0 +1,8 @@ + +.. _remoting-java: + +##################### + Remoting (Java) +##################### + +TBD \ No newline at end of file diff --git a/akka-docs/scala/index.rst b/akka-docs/scala/index.rst index 742dc04ea9..49f620b0ca 100644 --- a/akka-docs/scala/index.rst +++ b/akka-docs/scala/index.rst @@ -15,6 +15,7 @@ Scala API fault-tolerance dispatchers routing + remoting fsm testing extending-akka diff --git a/akka-docs/scala/remoting.rst b/akka-docs/scala/remoting.rst new file mode 100644 index 0000000000..cecba79215 --- /dev/null +++ b/akka-docs/scala/remoting.rst @@ -0,0 +1,84 @@ + +.. _remoting-scala: + +################# + Remoting (Scala) +################# + +For an introduction of remoting capabilities of Akka please see :ref:`remoting`. + +Preparing your ActorSystem for Remoting +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +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” + } + } + } + } + +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. + +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 From 9b39b9411feeb654aa70f99a692ce9a2dc4caf63 Mon Sep 17 00:00:00 2001 From: Henrik Engstrom Date: Thu, 15 Dec 2011 21:16:19 +0100 Subject: [PATCH 2/3] Fixed all comments related to remoting. Added new serialization section in documentation. See #1175. See #1536. --- akka-docs/intro/what-is-akka.rst | 4 +- .../docs/remoting/RemoteActorExample.java | 18 ++++ akka-docs/java/index.rst | 1 + akka-docs/java/remoting.rst | 93 ++++++++++++++++++- akka-docs/java/serialization.rst | 12 +++ akka-docs/scala/index.rst | 1 + akka-docs/scala/remoting.rst | 19 ++++ akka-docs/scala/serialization.rst | 12 +++ 8 files changed, 157 insertions(+), 3 deletions(-) create mode 100644 akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java create mode 100644 akka-docs/java/serialization.rst create mode 100644 akka-docs/scala/serialization.rst diff --git a/akka-docs/intro/what-is-akka.rst b/akka-docs/intro/what-is-akka.rst index 0041a41fde..6cc7c591c0 100644 --- a/akka-docs/intro/what-is-akka.rst +++ b/akka-docs/intro/what-is-akka.rst @@ -50,8 +50,8 @@ provide truly fault-tolerant systems. See :ref:`fault-tolerance-scala` and :ref:`fault-tolerance-java` -Transparent Remoting --------------------- +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. 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..e281a6d522 --- /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/theActor"); + //#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 5f886c9bd6..fbc94dbc61 100644 --- a/akka-docs/java/index.rst +++ b/akka-docs/java/index.rst @@ -16,4 +16,5 @@ Java API dispatchers routing remoting + serialization extending-akka diff --git a/akka-docs/java/remoting.rst b/akka-docs/java/remoting.rst index 9a47790b99..8f91679d1b 100644 --- a/akka-docs/java/remoting.rst +++ b/akka-docs/java/remoting.rst @@ -5,4 +5,95 @@ Remoting (Java) ##################### -TBD \ No newline at end of file +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 + +To use an actor on a remote node: + + .. includecode:: code/akka/docs/remoting/RemoteActorExample.java#remoteNodeActor + +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 49f620b0ca..898a74f905 100644 --- a/akka-docs/scala/index.rst +++ b/akka-docs/scala/index.rst @@ -16,6 +16,7 @@ Scala API dispatchers routing remoting + serialization fsm testing extending-akka diff --git a/akka-docs/scala/remoting.rst b/akka-docs/scala/remoting.rst index cecba79215..b20d959c46 100644 --- a/akka-docs/scala/remoting.rst +++ b/akka-docs/scala/remoting.rst @@ -10,6 +10,14 @@ 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 { @@ -54,12 +62,23 @@ The "app" in this case refers to the name of the ``ActorSystem``:: } } +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 = actorFor("/serviceA/retrieval") + +To use an actor on a remote node:: + + val actor = actorFor("akka://app@10.0.0.1:2552/user/theActor") + 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 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 From 215c77672c6bb3d197af7c21d361096a886557a5 Mon Sep 17 00:00:00 2001 From: Henrik Engstrom Date: Thu, 15 Dec 2011 23:47:12 +0100 Subject: [PATCH 3/3] Fixed even more comments on the remoting. See #1175 --- .../code/akka/docs/remoting/RemoteActorExample.java | 2 +- akka-docs/java/remoting.rst | 10 +++++++--- akka-docs/scala/remoting.rst | 10 +++++++--- 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java b/akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java index e281a6d522..8dd48aee4c 100644 --- a/akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java +++ b/akka-docs/java/code/akka/docs/remoting/RemoteActorExample.java @@ -9,7 +9,7 @@ public class RemoteActorExample extends UntypedActor { //#localNodeActor //#remoteNodeActor - ActorRef a2 = getContext().actorFor("akka://app@10.0.0.1:2552/user/theActor"); + ActorRef a2 = getContext().actorFor("akka://app@10.0.0.1:2552/user/serviceA/retrieval"); //#remoteNodeActor public void onReceive(Object message) throws Exception { diff --git a/akka-docs/java/remoting.rst b/akka-docs/java/remoting.rst index 8f91679d1b..15eacc3f4c 100644 --- a/akka-docs/java/remoting.rst +++ b/akka-docs/java/remoting.rst @@ -61,11 +61,15 @@ The "app" in this case refers to the name of the ``ActorSystem``:: 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 +.. includecode:: code/akka/docs/remoting/RemoteActorExample.java#localNodeActor -To use an actor on a remote node: +This will obtain an ``ActorRef`` on a remote node: - .. includecode:: code/akka/docs/remoting/RemoteActorExample.java#remoteNodeActor +.. 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 ^^^^^^^^^^^^^ diff --git a/akka-docs/scala/remoting.rst b/akka-docs/scala/remoting.rst index b20d959c46..78f7a598ad 100644 --- a/akka-docs/scala/remoting.rst +++ b/akka-docs/scala/remoting.rst @@ -65,11 +65,15 @@ The "app" in this case refers to the name of the ``ActorSystem``:: 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 = actorFor("/serviceA/retrieval") + val actor = context.actorFor("/serviceA/retrieval") -To use an actor on a remote node:: +This will obtain an ``ActorRef`` on a remote node:: - val actor = actorFor("akka://app@10.0.0.1:2552/user/theActor") + 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 ^^^^^^^^^^^^^