From 47f33c9294a80415b25ed74012bbee0bbec694d4 Mon Sep 17 00:00:00 2001 From: Taylor Leese Date: Tue, 20 Aug 2013 01:43:34 -0700 Subject: [PATCH] Add a few more details to the cluster client docs. --- akka-contrib/docs/cluster-client.rst | 17 ++++++++++++----- .../contrib/pattern/ClusterClientSpec.scala | 10 ++++------ 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/akka-contrib/docs/cluster-client.rst b/akka-contrib/docs/cluster-client.rst index bec4761cff..8bc06edc05 100644 --- a/akka-contrib/docs/cluster-client.rst +++ b/akka-contrib/docs/cluster-client.rst @@ -6,11 +6,14 @@ Cluster Client An actor system that is not part of the cluster can communicate with actors somewhere in the cluster via this ``ClusterClient``. The client can of course be part of another cluster. It only needs to know the location of one (or more) nodes to use as initial -contact point. It will establish a connection to a ``ClusterReceptionist`` somewhere in +contact points. It will establish a connection to a ``ClusterReceptionist`` somewhere in the cluster. It will monitor the connection to the receptionist and establish a new connection if the link goes down. When looking for a new receptionist it uses fresh contact points retrieved from previous establishment, or periodically refreshed contacts, -i.e. not necessarily the initial contact points. +i.e. not necessarily the initial contact points. Also, note it's necessary to change +``akka.actor.provider`` from ``akka.actor.LocalActorRefProvider`` to +``akka.remote.RemoteActorRefProvider`` or ``akka.cluster.ClusterActorRefProvider`` when using +the cluster client. The receptionist is supposed to be started on all nodes, or all nodes with specified role, in the cluster. The receptionist can be started with the ``ClusterReceptionistExtension`` @@ -50,8 +53,12 @@ directly to the actor in the cluster. An Example ---------- -On the cluster nodes you start the receptionist and register the actors that -should be available for the client. +On the cluster nodes first start the receptionist. Note, it is recommended to load the extension +when the actor system is started by defining it in the ``akka.extensions`` configuration property:: + + akka.extensions = ["akka.contrib.pattern.ClusterReceptionistExtension"] + +Next, register the actors that should be available for the client. .. includecode:: @contribSrc@/src/multi-jvm/scala/akka/contrib/pattern/ClusterClientSpec.scala#server @@ -83,7 +90,7 @@ The ``ClusterReceptionistExtension`` can be configured with the following proper Note that the ``ClusterReceptionistExtension`` uses the ``DistributedPubSubExtension``, which is described in :ref:`distributed-pub-sub`. -It is recommended to load the extension when the actor system is started by defining it in +It is recommended to load the extension when the actor system is started by defining it in the ``akka.extensions`` configuration property:: akka.extensions = ["akka.contrib.pattern.ClusterReceptionistExtension"] diff --git a/akka-contrib/src/multi-jvm/scala/akka/contrib/pattern/ClusterClientSpec.scala b/akka-contrib/src/multi-jvm/scala/akka/contrib/pattern/ClusterClientSpec.scala index 732be5559a..242cee629a 100644 --- a/akka-contrib/src/multi-jvm/scala/akka/contrib/pattern/ClusterClientSpec.scala +++ b/akka-contrib/src/multi-jvm/scala/akka/contrib/pattern/ClusterClientSpec.scala @@ -69,8 +69,6 @@ class ClusterClientSpec extends MultiNodeSpec(ClusterClientSpec) with STMultiNod def createReceptionist(): Unit = ClusterReceptionistExtension(system) - def receptionist: ClusterReceptionistExtension = ClusterReceptionistExtension(system) - def awaitCount(expected: Int): Unit = { awaitAssert { DistributedPubSubExtension(system).mediator ! DistributedPubSubMediator.Count @@ -93,7 +91,7 @@ class ClusterClientSpec extends MultiNodeSpec(ClusterClientSpec) with STMultiNod join(fourth, first) runOn(fourth) { val service = system.actorOf(Props(classOf[TestService], testActor), "testService") - receptionist.registerService(service) + ClusterReceptionistExtension(system).registerService(service) } runOn(first, second, third, fourth) { awaitCount(1) @@ -126,12 +124,12 @@ class ClusterClientSpec extends MultiNodeSpec(ClusterClientSpec) with STMultiNod //#server runOn(host1) { val serviceA = system.actorOf(Props[Service], "serviceA") - receptionist.registerService(serviceA) + ClusterReceptionistExtension(system).registerService(serviceA) } runOn(host2, host3) { val serviceB = system.actorOf(Props[Service], "serviceB") - receptionist.registerService(serviceB) + ClusterReceptionistExtension(system).registerService(serviceB) } //#server @@ -159,7 +157,7 @@ class ClusterClientSpec extends MultiNodeSpec(ClusterClientSpec) with STMultiNod "re-establish connection to receptionist when connection is lost" in within(30 seconds) { runOn(first, second, third, fourth) { val service2 = system.actorOf(Props(classOf[TestService], testActor), "service2") - receptionist.registerService(service2) + ClusterReceptionistExtension(system).registerService(service2) awaitCount(8) } enterBarrier("service2-replicated")