Class DistributedPubSubMediator
- All Implemented Interfaces:
Actor
,ActorLogging
,PerGroupingBuffer
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.
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.
You can send messages via the mediator on any node to registered actors on any other node. There is three 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.
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
DistributedPubSubMediator.Send
and all messages are delivered to one subscribe.
If all the subscribed actors have different group names, then this works like normal
DistributedPubSubMediator.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.
Not intended for subclassing by user code.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
static class
Scala API: Send this message to the mediator and it will reply with anInt
of the number of subscribers.static final class
static class
static final class
Reply toGetTopics
.static class
static class
static class
Send this message to the mediator and it will reply withDistributedPubSubMediator.CurrentTopics
containing the names of the (currently known) registered topic names.static class
INTERNAL APIstatic final class
static class
static final class
static class
static final class
static class
static final class
static class
static final class
static class
static final class
static class
static final class
static class
static final class
static class
static final class
static class
Nested classes/interfaces inherited from interface org.apache.pekko.actor.Actor
Actor.emptyBehavior$, Actor.ignoringBehavior$
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptioncluster()
scala.collection.immutable.Iterable<org.apache.pekko.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket>
collectDelta
(scala.collection.immutable.Map<Address, Object> otherVersions) context()
Scala API: Stores the context for this actor, including self, and sender.long
void
deltaCount_$eq
(long x$1) Java API: Send this message to the mediator and it will reply with anInteger
of the number of subscribers.scala.collection.immutable.Set<String>
Java API: Send this message to the mediator and it will reply withDistributedPubSubMediator.CurrentTopics
containing the names of the (currently known) registered topic names.void
gossip()
Gossip to peer nodes.void
boolean
newTopicActor
(String encTopic) scala.Function0<Object>
scala.collection.immutable.Set<Address>
nodes()
void
protected void
Scala API: Stores the context for this actor, including self, and sender.protected final void
The 'self' field holds the ActorRef for this actor.boolean
otherHasNewerVersions
(scala.collection.immutable.Map<Address, Object> otherVersions) void
postStop()
User overridable callback.void
preStart()
User overridable callback.static Props
props
(DistributedPubSubSettings settings) Scala API: Factory method forDistributedPubSubMediator
pekko.actor.Props
.void
prune()
scala.concurrent.duration.FiniteDuration
void
boolean
void
publishToEachGroup
(String path, Object msg) void
scala.PartialFunction<Object,
scala.runtime.BoxedUnit> receive()
Scala API: This defines the initial actor behavior, it must return a partial function with the actor logic.void
registerTopic
(ActorRef ref) scala.collection.immutable.Map<Address,
org.apache.pekko.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket> registry()
void
registry_$eq
(scala.collection.immutable.Map<Address, org.apache.pekko.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket> x$1) long
scala.Option<Address>
selectRandomNode
(scala.collection.immutable.IndexedSeq<Address> addresses) final ActorRef
self()
The 'self' field holds the ActorRef for this actor.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.apache.pekko.actor.Actor
aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, postRestart, preRestart, sender, supervisorStrategy, unhandled
Methods inherited from interface org.apache.pekko.actor.ActorLogging
_log_$eq, log
Methods inherited from interface org.apache.pekko.cluster.pubsub.PerGroupingBuffer
bufferOr, forwardMessages, forwardMessages, initializeGrouping, recreateAndForwardMessagesIfNeeded
-
Constructor Details
-
DistributedPubSubMediator
-
-
Method Details
-
props
Scala API: Factory method forDistributedPubSubMediator
pekko.actor.Props
. -
getTopicsInstance
Java API: Send this message to the mediator and it will reply withDistributedPubSubMediator.CurrentTopics
containing the names of the (currently known) registered topic names. -
getCountInstance
Java API: Send this message to the mediator and it will reply with anInteger
of the number of subscribers. -
context
Description copied from interface:Actor
Scala API: Stores the context for this actor, including self, and sender. It is implicit to support operations such asforward
.WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!
pekko.actor.ActorContext
is the Scala API.getContext
returns apekko.actor.AbstractActor.ActorContext
, which is the Java API of the actor context. -
self
Description copied from interface:Actor
The 'self' field holds the ActorRef for this actor. Can be used to send messages to itself:self ! message
-
org$apache$pekko$actor$Actor$_setter_$context_$eq
Description copied from interface:Actor
Scala API: Stores the context for this actor, including self, and sender. It is implicit to support operations such asforward
.WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!
pekko.actor.ActorContext
is the Scala API.getContext
returns apekko.actor.AbstractActor.ActorContext
, which is the Java API of the actor context.- Specified by:
org$apache$pekko$actor$Actor$_setter_$context_$eq
in interfaceActor
-
org$apache$pekko$actor$Actor$_setter_$self_$eq
Description copied from interface:Actor
The 'self' field holds the ActorRef for this actor. Can be used to send messages to itself:self ! message
- Specified by:
org$apache$pekko$actor$Actor$_setter_$self_$eq
in interfaceActor
-
cluster
-
removedTimeToLiveMillis
public long removedTimeToLiveMillis() -
gossipTask
-
pruneInterval
public scala.concurrent.duration.FiniteDuration pruneInterval() -
pruneTask
-
registry
public scala.collection.immutable.Map<Address,org.apache.pekko.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket> registry() -
registry_$eq
public void registry_$eq(scala.collection.immutable.Map<Address, org.apache.pekko.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket> x$1) -
nodes
-
nodes_$eq
-
deltaCount
public long deltaCount() -
deltaCount_$eq
public void deltaCount_$eq(long x$1) -
nextVersion
-
preStart
public void preStart()Description copied from interface:Actor
User overridable callback. Is called when an Actor is started. Actors are automatically started asynchronously when created. Empty default implementation. -
postStop
public void postStop()Description copied from interface:Actor
User overridable callback. Is called asynchronously after 'actor.stop()' is invoked. Empty default implementation. -
matchingRole
-
receive
Description copied from interface:Actor
Scala API: This defines the initial actor behavior, it must return a partial function with the actor logic. -
publish
-
publish$default$3
public boolean publish$default$3() -
publishToEachGroup
-
put
-
getCurrentTopics
-
registerTopic
-
mkKey
-
mkKey
-
myVersions
-
collectDelta
-
otherHasNewerVersions
-
gossip
public void gossip()Gossip to peer nodes. -
gossipTo
-
selectRandomNode
-
prune
public void prune() -
newTopicActor
-