=clt #17447 Split DistributedPubSub docs into java/scala
This commit is contained in:
Patrik Nordwall
parent
a93de9bf37
commit
6e28229fbe
9 changed files with 172 additions and 43 deletions
|
|
@ -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.
|
||||
*
|
||||
|
|
|
|||
|
|
@ -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
|
||||
^^^^^^^^^^^^^^
|
||||
|
|
|
|||
138
akka-docs/rst/java/distributed-pub-sub.rst
Normal file
138
akka-docs/rst/java/distributed-pub-sub.rst
Normal file
|
|
@ -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>
|
||||
|
|
@ -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
|
||||
----------------
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
|
|
|||
|
|
@ -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
|
||||
^^^^^^^^^^^^^^
|
||||
|
|
|
|||
|
|
@ -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
|
||||
are versioned. Deltas are disseminated in a scalable way to other nodes with
|
||||
a gossip protocol. 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.
|
||||
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 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 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 Small Example
|
||||
---------------
|
||||
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
----------------
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue