akka.cluster.pubsub

Class DistributedPubSubMediator

java.lang.Object

akka.cluster.pubsub.DistributedPubSubMediator

All Implemented Interfaces:

Actor, ActorLogging, PerGroupingBuffer

public class DistributedPubSubMediator
extends java.lang.Object
implements Actor, ActorLogging, PerGroupingBuffer

This actor 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.

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DistributedPubSubMediator.Count$
static class	DistributedPubSubMediator.CurrentTopics Reply to GetTopics.
static class	DistributedPubSubMediator.CurrentTopics$
static class	DistributedPubSubMediator.GetTopics
static class	DistributedPubSubMediator.GetTopics$ Send this message to the mediator and it will reply with DistributedPubSubMediator.CurrentTopics containing the names of the (currently known) registered topic names.
static class	DistributedPubSubMediator.Internal$ INTERNAL API
static class	DistributedPubSubMediator.Publish
static class	DistributedPubSubMediator.Publish$
static class	DistributedPubSubMediator.Put
static class	DistributedPubSubMediator.Put$
static class	DistributedPubSubMediator.Remove
static class	DistributedPubSubMediator.Remove$
static class	DistributedPubSubMediator.Send
static class	DistributedPubSubMediator.Send$
static class	DistributedPubSubMediator.SendToAll
static class	DistributedPubSubMediator.SendToAll$
static class	DistributedPubSubMediator.Subscribe
static class	DistributedPubSubMediator.Subscribe$
static class	DistributedPubSubMediator.SubscribeAck
static class	DistributedPubSubMediator.SubscribeAck$
static class	DistributedPubSubMediator.Unsubscribe
static class	DistributedPubSubMediator.Unsubscribe$
static class	DistributedPubSubMediator.UnsubscribeAck
static class	DistributedPubSubMediator.UnsubscribeAck$

Nested classes/interfaces inherited from interface akka.actor.Actor

Actor.emptyBehavior$, Actor.ignoringBehavior$

Constructor Summary

Constructors

Constructor and Description
DistributedPubSubMediator(DistributedPubSubSettings settings)

Method Summary

Modifier and Type	Method and Description
protected abstract static void	akka$actor$Actor$_setter_$context_$eq(ActorContext x$1)
protected abstract static void	akka$actor$Actor$_setter_$self_$eq(ActorRef x$1)
static void	akka$actor$ActorLogging$$_log_$eq(LoggingAdapter x$1)
static LoggingAdapter	akka$actor$ActorLogging$$_log()
protected abstract static void	akka$cluster$pubsub$PerGroupingBuffer$_setter_$akka$cluster$pubsub$PerGroupingBuffer$$buffers_$eq(MessageBufferMap<java.lang.String> x$1)
static MessageBufferMap<java.lang.String>	akka$cluster$pubsub$PerGroupingBuffer$$buffers()
protected static void	aroundPostRestart(java.lang.Throwable reason)
protected static void	aroundPostStop()
protected static void	aroundPreRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message)
protected static void	aroundPreStart()
protected static void	aroundReceive(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive, java.lang.Object msg)
static void	bufferOr(java.lang.String grouping, java.lang.Object message, ActorRef originalSender, scala.Function0<scala.runtime.BoxedUnit> action)
Cluster	cluster()
scala.collection.immutable.Iterable<akka.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket>	collectDelta(scala.collection.immutable.Map<Address,java.lang.Object> otherVersions)
ActorContext	context() Stores the context for this actor, including self, and sender.
long	deltaCount()
static void	forwardMessages(java.lang.String grouping, ActorRef recipient)
scala.collection.immutable.Set<java.lang.String>	getCurrentTopics()
static DistributedPubSubMediator.GetTopics	getTopicsInstance() 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.
void	gossip() Gossip to peer nodes.
Cancellable	gossipTask()
void	gossipTo(Address address)
static void	initializeGrouping(java.lang.String grouping)
static LoggingAdapter	log()
boolean	matchingRole(Member m)
java.lang.String	mkKey(ActorPath path)
java.lang.String	mkKey(ActorRef ref)
scala.collection.immutable.Map<Address,java.lang.Object>	myVersions()
ActorRef	newTopicActor(java.lang.String encTopic)
scala.Function0<java.lang.Object>	nextVersion()
scala.collection.immutable.Set<Address>	nodes()
boolean	otherHasNewerVersions(scala.collection.immutable.Map<Address,java.lang.Object> otherVersions)
static void	postRestart(java.lang.Throwable reason)
void	postStop() User overridable callback.
static void	preRestart(java.lang.Throwable reason, scala.Option<java.lang.Object> message)
void	preStart() User overridable callback.
static Props	props(DistributedPubSubSettings settings) Scala API: Factory method for DistributedPubSubMediator Props.
void	prune()
scala.concurrent.duration.FiniteDuration	pruneInterval()
Cancellable	pruneTask()
void	publish(java.lang.String path, java.lang.Object msg, boolean allButSelf)
void	publishToEachGroup(java.lang.String path, java.lang.Object msg)
void	put(java.lang.String key, scala.Option<ActorRef> valueOption)
scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit>	receive() This defines the initial actor behavior, it must return a partial function with the actor logic.
static void	recreateAndForwardMessagesIfNeeded(java.lang.String grouping, scala.Function0<ActorRef> recipient)
void	registerTopic(ActorRef ref)
scala.collection.immutable.Map<Address,akka.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket>	registry()
long	removedTimeToLiveMillis()
scala.Option<Address>	selectRandomNode(scala.collection.immutable.IndexedSeq<Address> addresses)
ActorRef	self() The 'self' field holds the ActorRef for this actor.
static ActorRef	sender()
static SupervisorStrategy	supervisorStrategy()
static void	unhandled(java.lang.Object message)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface akka.actor.Actor

aroundPostRestart, aroundPostStop, aroundPreRestart, aroundPreStart, aroundReceive, postRestart, preRestart, sender, supervisorStrategy, unhandled

Methods inherited from interface akka.actor.ActorLogging

log

Methods inherited from interface akka.cluster.pubsub.PerGroupingBuffer

bufferOr, forwardMessages, forwardMessages, initializeGrouping, recreateAndForwardMessagesIfNeeded

Constructor Detail

DistributedPubSubMediator

public DistributedPubSubMediator(DistributedPubSubSettings settings)

Method Detail

props

public static Props props(DistributedPubSubSettings settings)

Scala API: Factory method for DistributedPubSubMediator Props.

Parameters:

settings - (undocumented)

Returns:

(undocumented)

getTopicsInstance

public static DistributedPubSubMediator.GetTopics getTopicsInstance()

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.

Returns:

(undocumented)

sender

public static final ActorRef sender()

aroundReceive

protected static void aroundReceive(scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive,
                                    java.lang.Object msg)

aroundPreStart

protected static void aroundPreStart()

aroundPostStop

protected static void aroundPostStop()

aroundPreRestart

protected static void aroundPreRestart(java.lang.Throwable reason,
                                       scala.Option<java.lang.Object> message)

aroundPostRestart

protected static void aroundPostRestart(java.lang.Throwable reason)

supervisorStrategy

public static SupervisorStrategy supervisorStrategy()

preRestart

public static void preRestart(java.lang.Throwable reason,
                              scala.Option<java.lang.Object> message)
                       throws java.lang.Exception

Throws:

java.lang.Exception

postRestart

public static void postRestart(java.lang.Throwable reason)
                        throws java.lang.Exception

Throws:

java.lang.Exception

unhandled

public static void unhandled(java.lang.Object message)

akka$actor$Actor$_setter_$context_$eq

protected abstract static void akka$actor$Actor$_setter_$context_$eq(ActorContext x$1)

akka$actor$Actor$_setter_$self_$eq

protected abstract static void akka$actor$Actor$_setter_$self_$eq(ActorRef x$1)

akka$actor$ActorLogging$$_log

public static LoggingAdapter akka$actor$ActorLogging$$_log()

akka$actor$ActorLogging$$_log_$eq

public static void akka$actor$ActorLogging$$_log_$eq(LoggingAdapter x$1)

log

public static LoggingAdapter log()

akka$cluster$pubsub$PerGroupingBuffer$$buffers

public static MessageBufferMap<java.lang.String> akka$cluster$pubsub$PerGroupingBuffer$$buffers()

bufferOr

public static void bufferOr(java.lang.String grouping,
                            java.lang.Object message,
                            ActorRef originalSender,
                            scala.Function0<scala.runtime.BoxedUnit> action)

recreateAndForwardMessagesIfNeeded

public static void recreateAndForwardMessagesIfNeeded(java.lang.String grouping,
                                                      scala.Function0<ActorRef> recipient)

forwardMessages

public static void forwardMessages(java.lang.String grouping,
                                   ActorRef recipient)

initializeGrouping

public static void initializeGrouping(java.lang.String grouping)

akka$cluster$pubsub$PerGroupingBuffer$_setter_$akka$cluster$pubsub$PerGroupingBuffer$$buffers_$eq

protected abstract static void akka$cluster$pubsub$PerGroupingBuffer$_setter_$akka$cluster$pubsub$PerGroupingBuffer$$buffers_$eq(MessageBufferMap<java.lang.String> x$1)

context

public ActorContext context()

Description copied from interface: Actor

Stores the context for this actor, including self, and sender. It is implicit to support operations such as forward.

WARNING: Only valid within the Actor itself, so do not close over it and publish it to other threads!

ActorContext is the Scala API. getContext returns a UntypedActorContext, which is the Java API of the actor context.

Specified by:

context in interface Actor

Returns:

(undocumented)

self

public final ActorRef 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
 

Specified by:

self in interface Actor

Returns:

(undocumented)

cluster

public Cluster cluster()

removedTimeToLiveMillis

public long removedTimeToLiveMillis()

gossipTask

public Cancellable gossipTask()

pruneInterval

public scala.concurrent.duration.FiniteDuration pruneInterval()

pruneTask

public Cancellable pruneTask()

registry

public scala.collection.immutable.Map<Address,akka.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket> registry()

nodes

public scala.collection.immutable.Set<Address> nodes()

deltaCount

public long deltaCount()

nextVersion

public scala.Function0<java.lang.Object> 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.

Specified by:

preStart in interface Actor

postStop

public void postStop()

Description copied from interface: Actor

User overridable callback.

Is called asynchronously after 'actor.stop()' is invoked. Empty default implementation.

Specified by:

postStop in interface Actor

matchingRole

public boolean matchingRole(Member m)

receive

public scala.PartialFunction<java.lang.Object,scala.runtime.BoxedUnit> receive()

Description copied from interface: Actor

This defines the initial actor behavior, it must return a partial function with the actor logic.

Specified by:

receive in interface Actor

Returns:

(undocumented)

publish

public void publish(java.lang.String path,
                    java.lang.Object msg,
                    boolean allButSelf)

publishToEachGroup

public void publishToEachGroup(java.lang.String path,
                               java.lang.Object msg)

put

public void put(java.lang.String key,
                scala.Option<ActorRef> valueOption)

getCurrentTopics

public scala.collection.immutable.Set<java.lang.String> getCurrentTopics()

registerTopic

public void registerTopic(ActorRef ref)

mkKey

public java.lang.String mkKey(ActorRef ref)

mkKey

public java.lang.String mkKey(ActorPath path)

myVersions

public scala.collection.immutable.Map<Address,java.lang.Object> myVersions()

collectDelta

public scala.collection.immutable.Iterable<akka.cluster.pubsub.DistributedPubSubMediator.Internal.Bucket> collectDelta(scala.collection.immutable.Map<Address,java.lang.Object> otherVersions)

otherHasNewerVersions

public boolean otherHasNewerVersions(scala.collection.immutable.Map<Address,java.lang.Object> otherVersions)

gossip

public void gossip()

Gossip to peer nodes.

gossipTo

public void gossipTo(Address address)

selectRandomNode

public scala.Option<Address> selectRandomNode(scala.collection.immutable.IndexedSeq<Address> addresses)

prune

public void prune()

newTopicActor

public ActorRef newTopicActor(java.lang.String encTopic)