=clt #17447 Split DistributedPubSub docs into java/scala

akka-cluster-tools/src/main/scala/akka/cluster/pubsub/DistributedPubSubMediator.scala

@@ -182,14 +182,25 @@ object DistributedPubSubMediator {
   }
 
   sealed abstract class GetTopics
+
+  /**
+   * Send this message to the mediator and it will reply with
+   * [[CurrentTopics]] containing the names of the (currently known)
+   * registered topic names.
+   */
   @SerialVersionUID(1L)
   case object GetTopics extends GetTopics
 
   /**
-   * Java API
+   * Java API: Send this message to the mediator and it will reply with
+   * [[DistributedPubSubMediator.CurrentTopics]] containing the names of the (currently known)
+   * registered topic names.
    */
   def getTopicsInstance: GetTopics = GetTopics
 
+  /**
+   * Reply to `GetTopics`.
+   */
   @SerialVersionUID(1L)
   final case class CurrentTopics(topics: Set[String]) {
     /**
@@ -348,7 +359,7 @@ trait DistributedPubSubMessage extends Serializable
  * the entries to peer actors among all cluster nodes or a group of nodes
  * tagged with a specific role.
  *
- * The `DistributedPubSubMediator` is supposed to be started on all nodes,
+ * The `DistributedPubSubMediator` actor is supposed to be started on all nodes,
  * or all nodes with specified role, in the cluster. The mediator can be
  * started with the [[DistributedPubSub]] extension or as an ordinary actor.
  *

akka-docs/rst/java/cluster-usage.rst

@@ -331,7 +331,7 @@ Publish-subscribe messaging between actors in the cluster, and point-to-point me
 using the logical path of the actors, i.e. the sender does not have to know on which
 node the destination actor is running.
 
-See :ref:`distributed-pub-sub` in the contrib module.
+See :ref:`distributed-pub-sub-scala`.
 
 Cluster Client
 ^^^^^^^^^^^^^^

akka-docs/rst/java/distributed-pub-sub.rst

@@ -0,0 +1,138 @@
+.. _distributed-pub-sub-java:
+
+Distributed Publish Subscribe in Cluster
+========================================
+
+How do I send a message to an actor without knowing which node it is running on?
+
+How do I send messages to all actors in the cluster that have registered interest
+in a named topic?
+
+This pattern provides a mediator actor, ``akka.cluster.pubsub.DistributedPubSubMediator``,
+that manages a registry of actor references and replicates the entries to peer
+actors among all cluster nodes or a group of nodes tagged with a specific role.
+
+The ``DistributedPubSubMediator`` actor is supposed to be started on all nodes,
+or all nodes with specified role, in the cluster. The mediator can be
+started with the ``DistributedPubSub`` extension or as an ordinary actor.
+
+The registry is eventually consistent, i.e. changes are not immediately visible at 
+other nodes, but typically they will be fully replicated to all other nodes after
+a few seconds. Changes are only performed in the own part of the registry and those 
+changes are versioned. Deltas are disseminated in a scalable way to other nodes with
+a gossip protocol.
+
+You can send messages via the mediator on any node to registered actors on
+any other node. There are four modes of message delivery.
+
+**1. DistributedPubSubMediator.Send**
+
+The message will be delivered to one recipient with a matching path, if any such
+exists in the registry. If several entries match the path the message will be sent
+via the supplied ``RoutingLogic`` (default random) to one destination. The sender() of the
+message can specify that local affinity is preferred, i.e. the message is sent to an actor
+in the same local actor system as the used mediator actor, if any such exists, otherwise
+route to any other matching entry. A typical usage of this mode is private chat to one
+other user in an instant messaging application. It can also be used for distributing
+tasks to registered workers, like a cluster aware router where the routees dynamically
+can register themselves.
+
+**2. DistributedPubSubMediator.SendToAll**
+
+The message will be delivered to all recipients with a matching path. Actors with
+the same path, without address information, can be registered on different nodes.
+On each node there can only be one such actor, since the path is unique within one
+local actor system. Typical usage of this mode is to broadcast messages to all replicas
+with the same path, e.g. 3 actors on different nodes that all perform the same actions,
+for redundancy. You can also optionally specify a property (``allButSelf``) deciding
+if the message should be sent to a matching path on the self node or not.
+
+**3. DistributedPubSubMediator.Publish**
+
+Actors may be registered to a named topic instead of path. This enables many subscribers
+on each node. The message will be delivered to all subscribers of the topic. For
+efficiency the message is sent over the wire only once per node (that has a matching topic),
+and then delivered to all subscribers of the local topic representation. This is the
+true pub/sub mode. A typical usage of this mode is a chat room in an instant messaging
+application.
+
+**4. DistributedPubSubMediator.Publish with sendOneMessageToEachGroup**
+
+Actors may be subscribed to a named topic with an optional property (``group``).
+If subscribing with a group name, each message published to a topic with the
+(``sendOneMessageToEachGroup``) flag is delivered via the supplied ``RoutingLogic``
+(default random) to one actor within each subscribing group.
+If all the subscribed actors have the same group name, then this works just like
+``Send`` and all messages are delivered to one subscriber.
+If all the subscribed actors have different group names, then this works like
+normal ``Publish`` and all messages are broadcast to all subscribers.
+
+You register actors to the local mediator with ``DistributedPubSubMediator.Put`` or
+``DistributedPubSubMediator.Subscribe``. ``Put`` is used together with ``Send`` and
+``SendToAll`` message delivery modes. The ``ActorRef`` in ``Put`` must belong to the same
+local actor system as the mediator. ``Subscribe`` is used together with ``Publish``.
+Actors are automatically removed from the registry when they are terminated, or you
+can explicitly remove entries with ``DistributedPubSubMediator.Remove`` or
+``DistributedPubSubMediator.Unsubscribe``.
+
+Successful ``Subscribe`` and ``Unsubscribe`` is acknowledged with
+``DistributedPubSubMediator.SubscribeAck`` and ``DistributedPubSubMediator.UnsubscribeAck``
+replies.
+
+A Small Example
+---------------
+
+A subscriber actor:
+
+.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#subscriber
+
+Subscriber actors can be started on several nodes in the cluster, and all will receive
+messages published to the "content" topic.
+
+.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#start-subscribers
+
+A simple actor that publishes to this "content" topic:
+
+.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#publisher
+
+It can publish messages to the topic from anywhere in the cluster:
+
+.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#publish-message
+
+DistributedPubSub Extension
+---------------------------
+
+In the example above the mediator is started and accessed with the ``akka.cluster.pubsub.DistributedPubSub`` extension.
+That is convenient and perfectly fine in most cases, but it can be good to know that it is possible to
+start the mediator actor as an ordinary actor and you can have several different mediators at the same
+time to be able to divide a large number of actors/topics to different mediators. For example you might
+want to use different cluster roles for different mediators.
+
+The ``DistributedPubSub`` extension can be configured with the following properties:
+
+.. includecode:: ../../../akka-cluster-tools/src/main/resources/reference.conf#pub-sub-ext-config
+
+It is recommended to load the extension when the actor system is started by defining it in
+``akka.extensions`` configuration property. Otherwise it will be activated when first used
+and then it takes a while for it to be populated.
+
+::
+
+   akka.extensions = ["akka.cluster.pubsub.DistributedPubSub"]
+
+Dependencies
+------------
+
+To use the Cluster Singleton you must add the following dependency in your project.
+
+sbt::
+
+    "com.typesafe.akka" %% "akka-cluster-tools" % "@version@" @crossString@
+
+maven::
+
+  <dependency>
+    <groupId>com.typesafe.akka</groupId>
+    <artifactId>akka-cluster-tools_@binVersion@</artifactId>
+    <version>@version@</version>
+  </dependency>

akka-docs/rst/java/event-bus.rst

@@ -152,7 +152,7 @@ Similarly to `Actor Classification`_, :class:`EventStream` will automatically re
 
 .. note::
    The event stream is a *local facility*, meaning that it will *not* distribute events to other nodes in a clustered environment (unless you subscribe a Remote Actor to the stream explicitly).
-   If you need to broadcast events in an Akka cluster, *without* knowing your recipients explicitly (i.e. obtaining their ActorRefs), you may want to look into: :ref:`distributed-pub-sub`.
+   If you need to broadcast events in an Akka cluster, *without* knowing your recipients explicitly (i.e. obtaining their ActorRefs), you may want to look into: :ref:`distributed-pub-sub-java`.
 
 Default Handlers
 ----------------

akka-docs/rst/java/index-network.rst

@@ -7,7 +7,7 @@ Networking
    ../common/cluster
    cluster-usage
    cluster-singleton
-   ../scala/distributed-pub-sub
+   distributed-pub-sub
    ../scala/cluster-client
    cluster-sharding
    cluster-metrics

akka-docs/rst/scala/cluster-client.rst

@@ -102,7 +102,7 @@ The ``ClusterClientReceptionist`` can be configured with the following propertie
 .. includecode:: ../../../akka-cluster-tools/src/main/resources/reference.conf#receptionist-ext-config
 
 Note that the ``ClusterClientReceptionist`` uses the ``DistributedPubSub`` extension, which is described
-in :ref:`distributed-pub-sub`.
+in :ref:`distributed-pub-sub-scala`.
 
 It is recommended to load the extension when the actor system is started by defining it in the
 ``akka.extensions`` configuration property::

akka-docs/rst/scala/cluster-usage.rst

@@ -325,7 +325,7 @@ Publish-subscribe messaging between actors in the cluster, and point-to-point me
 using the logical path of the actors, i.e. the sender does not have to know on which
 node the destination actor is running.
 
-See :ref:`distributed-pub-sub` in the contrib module.
+See :ref:`distributed-pub-sub-scala`.
 
 Cluster Client
 ^^^^^^^^^^^^^^

akka-docs/rst/scala/distributed-pub-sub.rst

@@ -1,4 +1,4 @@
-.. _distributed-pub-sub:
+.. _distributed-pub-sub-scala:
 
 Distributed Publish Subscribe in Cluster
 ========================================
@@ -12,18 +12,18 @@ This pattern provides a mediator actor, ``akka.cluster.pubsub.DistributedPubSubM
 that manages a registry of actor references and replicates the entries to peer
 actors among all cluster nodes or a group of nodes tagged with a specific role.
 
-The `DistributedPubSubMediator` is supposed to be started on all nodes,
+The ``DistributedPubSubMediator`` actor is supposed to be started on all nodes,
 or all nodes with specified role, in the cluster. The mediator can be
-started with the ``DistributedPubSub`` or as an ordinary actor.
+started with the ``DistributedPubSub`` extension or as an ordinary actor.
 
-Changes are only performed in the own part of the registry and those changes
+The registry is eventually consistent, i.e. changes are not immediately visible at 
-are versioned. Deltas are disseminated in a scalable way to other nodes with
+other nodes, but typically they will be fully replicated to all other nodes after
-a gossip protocol. The registry is eventually consistent, i.e. changes are not
+a few seconds. Changes are only performed in the own part of the registry and those 
-immediately visible at other nodes, but typically they will be fully replicated
+changes are versioned. Deltas are disseminated in a scalable way to other nodes with
-to all other nodes after a few seconds.
+a gossip protocol.
 
 You can send messages via the mediator on any node to registered actors on
-any other node. There is four modes of message delivery.
+any other node. There are four modes of message delivery.
 
 **1. DistributedPubSubMediator.Send**
 
@@ -79,28 +79,8 @@ Successful ``Subscribe`` and ``Unsubscribe`` is acknowledged with
 ``DistributedPubSubMediator.SubscribeAck`` and ``DistributedPubSubMediator.UnsubscribeAck``
 replies.
 
-A Small Example in Java
+A Small Example
------------------------
+---------------
-
-A subscriber actor:
-
-.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#subscriber
-
-Subscriber actors can be started on several nodes in the cluster, and all will receive
-messages published to the "content" topic.
-
-.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#start-subscribers
-
-A simple actor that publishes to this "content" topic:
-
-.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#publisher
-
-It can publish messages to the topic from anywhere in the cluster:
-
-.. includecode:: ../../../akka-cluster-tools/src/test/java/akka/cluster/pubsub/DistributedPubSubMediatorTest.java#publish-message
-
-A Small Example in Scala
-------------------------
 
 A subscriber actor:
 
@@ -122,16 +102,16 @@ It can publish messages to the topic from anywhere in the cluster:
 A more comprehensive sample is available in the `Typesafe Activator <http://www.typesafe.com/platform/getstarted>`_
 tutorial named `Akka Clustered PubSub with Scala! <http://www.typesafe.com/activator/template/akka-clustering>`_.
 
-DistributedPubSub
+DistributedPubSub Extension
---------------------------
+---------------------------
 
-In the example above the mediator is started and accessed with the ``akka.cluster.pubsub.DistributedPubSub``.
+In the example above the mediator is started and accessed with the ``akka.cluster.pubsub.DistributedPubSub`` extension.
 That is convenient and perfectly fine in most cases, but it can be good to know that it is possible to
 start the mediator actor as an ordinary actor and you can have several different mediators at the same
 time to be able to divide a large number of actors/topics to different mediators. For example you might
 want to use different cluster roles for different mediators.
 
-The ``DistributedPubSub`` can be configured with the following properties:
+The ``DistributedPubSub`` extension can be configured with the following properties:
 
 .. includecode:: ../../../akka-cluster-tools/src/main/resources/reference.conf#pub-sub-ext-config
 

akka-docs/rst/scala/event-bus.rst

@@ -147,7 +147,7 @@ Similarly to `Actor Classification`_, :class:`EventStream` will automatically re
 
 .. note::
    The event stream is a *local facility*, meaning that it will *not* distribute events to other nodes in a clustered environment (unless you subscribe a Remote Actor to the stream explicitly).
-   If you need to broadcast events in an Akka cluster, *without* knowing your recipients explicitly (i.e. obtaining their ActorRefs), you may want to look into: :ref:`distributed-pub-sub`.
+   If you need to broadcast events in an Akka cluster, *without* knowing your recipients explicitly (i.e. obtaining their ActorRefs), you may want to look into: :ref:`distributed-pub-sub-scala`.
 
 Default Handlers
 ----------------