Add a few more details to the cluster client docs.

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
+On the cluster nodes first start the receptionist. Note, it is recommended to load the extension 
-should be available for the client.
+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"]

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")