Updated and corrected documentation for remoting. See #1546
This commit is contained in:
Henrik Engstrom
parent
e160179aa9
commit
dfe7e4ef63
2 changed files with 63 additions and 33 deletions
|
|
@ -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 <https://github.com/jboner/akka/blob/master/akka-remote/src/main/resources/reference.conf#L39>`_
|
||||
|
||||
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://<actorsystemname>@<hostname>:<port>/<actor path>
|
||||
akka://<actorsystemname>@<hostname>:<port>/<actor path>
|
||||
|
||||
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 <https://github.com/jboner/akka/tree/master/akka-samples/akka-sample-remote>`_
|
||||
|
||||
Serialization
|
||||
^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue