diff --git a/akka-docs/scala/remoting.rst b/akka-docs/scala/remoting.rst index 8201e37815..189beb1862 100644 --- a/akka-docs/scala/remoting.rst +++ b/akka-docs/scala/remoting.rst @@ -17,67 +17,97 @@ 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``:: +To enable remote capabilities in your Akka project you should, at a minimum, add the following changes +to your ``application.conf`` file:: akka { actor { - provider = "akka.remote.RemoteActorRefProvider" + provider = "akka.remote.RemoteActorRefProvider" } - } - -After that you must also add the following settings:: - - akka { remote { + transport = "akka.remote.netty.NettyRemoteSupport" 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) + hostname = "127.0.0.1" port = 2552 } - } + } + cluster.nodename = "someUniqueNameInTheCluster1" } -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 +As you can see in the example above there are four things you need to add to get started: + +* Change provider from ``LocalActorRefProvider`` to ``RemoteActorRefProvider`` +* Add host name - the machine you want to run the actor system on +* Add port number - the port the actor system should listen on +* Add cluster node name - must be a unique name in the cluster + +The example above only illustrates the bare minimum of properties you have to add to enable remoting. +There are lots of more properties that are related to remoting in Akka. We refer to the following reference file for more information: * `reference.conf of akka-remote `_ +Types of Remote Interaction +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Akka has two ways of using remoting: + +* Lookup : used to look up an actor on a remote node +* Creation : used to create an actor on a remote node + +In the next sections these ways are described in detail. + Looking up Remote Actors ^^^^^^^^^^^^^^^^^^^^^^^^ -``actorFor(path)`` will obtain an ``ActorRef`` to an Actor on a remote node:: +``actorFor(path)`` will obtain an ``ActorRef`` to an Actor on a remote node, e.g.:: 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://@:/ + akka://@:/ + +Once you a reference to the actor you can interact with it they same way you would with a local actor, e.g.:: + + actor ! "Pretty awesome feature" Creating Actors Remotely ^^^^^^^^^^^^^^^^^^^^^^^^ -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``:: +If you want to use the creation functionality in Akka remoting you have to further amend the +``application.conf`` file in the following way:: akka { actor { - deployment { - /serviceA/retrieval { - remote = “akka://app@10.0.0.1:2552” - } - } + provider = "akka.remote.RemoteActorRefProvider" + deployment { /sampleActor { + remote = "akka://sampleActorSystem@127.0.0.1:2553" + }} } - } + ... -Logical path lookup is supported on the node you are on, i.e. to use the -actor created above you would do the following:: +The configuration above instructs Akka to react specially once when an actor at path /actorName is created, i.e. +using system.actorOf(Props(...), "sampleActor"). This specific actor will not only be instantiated, +but instead the remote daemon of the remote system will be asked to create the actor instead, +which is at sampleActorSystem@127.0.0.1:2553 in this sample. - val actor = context.actorFor("/serviceA/retrieval") +Once you have configured the properties above you would do the following in code:: + + class SampleActor extends Actor { def receive = { case _ => println("Got something") } } + + val actor = context.actorOf(Props[SampleActor], "sampleActor") + actor ! "Pretty slick" + +``SampleActor`` has to be available to the runtimes using it, i.e. the classloader of the +actor systems has to have a JAR containing the class. + +Remote Sample Code +^^^^^^^^^^^^^^^^^^ + +There is a more extensive remote example that comes with the Akka distribution. +Please have a look here for more information: +`Remote Sample `_ Serialization ^^^^^^^^^^^^^ diff --git a/akka-samples/akka-sample-remote/README.rst b/akka-samples/akka-sample-remote/README.rst index 24f63ccc86..0732c33327 100644 --- a/akka-samples/akka-sample-remote/README.rst +++ b/akka-samples/akka-sample-remote/README.rst @@ -70,7 +70,7 @@ Open up a new terminal window and run SBT once more: > run -Select to run "sample.remote.calculator.LookupApp" which in the case below is number 1: +Select to run "sample.remote.calculator.LookupApp" which in the case below is number 1:: Multiple main classes detected, select one to run: @@ -80,7 +80,7 @@ Select to run "sample.remote.calculator.LookupApp" which in the case below is nu Enter number: 1 -Now you should see something like this: +Now you should see something like this:: [info] Running sample.remote.calculator.LookupApp [INFO] [12/22/2011 14:54:38.630] [run-main] [ActorSystem] REMOTE: RemoteServerStarted@akka://LookupApplication@127.0.0.1:2553 @@ -102,7 +102,7 @@ Once more you should open a new terminal window and run SBT: > run -Select to run "sample.remote.calculator.CreationApp" which in the case below is number 2: +Select to run "sample.remote.calculator.CreationApp" which in the case below is number 2:: Multiple main classes detected, select one to run: @@ -112,7 +112,7 @@ Select to run "sample.remote.calculator.CreationApp" which in the case below is Enter number: 2 -Now you should see something like this: +Now you should see something like this:: [info] Running sample.remote.calculator.CreationApp [INFO] [12/22/2011 14:57:02.150] [run-main] [ActorSystem] REMOTE: RemoteServerStarted@akka://RemoteCreation@127.0.0.1:2554