akka.persistence.multidc.scaladsl

Class ReplicatedEntity<Command,Event,State>

java.lang.Object

akka.persistence.multidc.internal.InternalReplicatedEntity<Command,Event,State>

akka.persistence.multidc.scaladsl.ReplicatedEntity<Command,Event,State>

Type Parameters:

Command - the super type of all commands

Event - the super type of all events

State - the type of the state

public abstract class ReplicatedEntity<Command,Event,State>
extends InternalReplicatedEntity<Command,Event,State>

A ReplicatedEntity has a stable entity identifier, with which it can be accessed from anywhere in the cluster. It is run by an actor and the state is persistent using event sourcing.

initialState and behavior are abstract methods that your concrete subclass must implement. The behavior is defined as a set of handlers given a state. The handlers are functions to process incoming commands.

Persistent and replicated events are applied to the state with the eventHandler method.

The ReplicatedEntity receives commands of type Command that can be validated before persisting state changes as events of type Event. The functions that process incoming commands are registered in the CommandHandler using onCommand of the CommandHandler.

A command may also be read-only and only perform some side-effect, such as replying to the request. Such command handlers are registered using onReadOnlyCommand of the CommandHandler. Replies are sent with the sender() ActorRef in the context or an ActorRef that is passed in the command.

A command handler returns a Effect directive that defines what event or events, if any, to persist. Use the thenPersist, thenPersistAll or done methods of the context that is passed to the command handler function to create the Effect directive.

When an event has been persisted successfully the state of type State is updated by applying the event to the current state by invoking the eventHandler. The eventHandler returns the new state. The state must be immutable, so you return a new instance of the state. Current state is passed as parameter to the event handler. The same event handlers are also used when the entity is started up to recover its state from the stored events.

After persisting an event, external side effects can be performed with the andThen function of the Effect directive. A typical side effect is to reply to the request to confirm that it was performed successfully. Replies are sent with the sender() ActorRef in the context or an ActorRef that is passed in the command.

The event handlers are typically only updating the state, but they may also change the behavior of the entity in the sense that new functions for processing commands and events may be defined for a given state. This is useful when implementing finite state machine (FSM) like entities.

When the entity is started the state is recovered by replaying stored events. To reduce this recovery time the entity may start the recovery from a snapshot of the state and then only replaying the events that were stored after the snapshot. Such snapshots are automatically saved after a configured number of persisted events.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ReplicatedEntity.ActorContext Actor context for ReplicatedEntity with somewhat limited capabilities and additional functionality specifically replicated entities.
static interface	ReplicatedEntity.CommandContext Actor context for ReplicatedEntity with somewhat limited capabilities and additional functionality specifically replicated entities.
static interface	ReplicatedEntity.CommandHandler<Command,Event,State> Not for user extension.
static class	ReplicatedEntity.CommandHandler$ INTERNAL API
static class	ReplicatedEntity.CommandHandlerFactories<Command,Event,State> CommandHandler defines how to react on a commands and optionally functions for other signals, e.g.
static interface	ReplicatedEntity.EventTaggingContext Context passed to `ReplicatedEntity.tagsFor` when tagging events.
static interface	ReplicatedEntity.EventTriggerContext Context passed to `ReplicatedEntity.eventTrigger`.

Constructor Summary

Constructors

Constructor and Description
ReplicatedEntity()

Method Summary

Modifier and Type	Method and Description
static <Command,Event,State> akka.actor.Props	clusterShardingProps(java.lang.String entityTypeName, scala.Function0<ReplicatedEntity<Command,Event,State>> entityFactory, PersistenceMultiDcSettings settings, scala.reflect.ClassTag<Command> evidence$3) The Props for the actor that can run a ReplicatedEntity with Cluster Sharding.
abstract ReplicatedEntity.CommandHandler<Command,Event,State>	commandHandler() Abstract method that must be implemented by concrete subclass to define the command handlers of the entity.
protected ReplicatedEntity.CommandHandlerFactories<Command,Event,State>	CommandHandler()
protected EffectFactories<Command,Event,State>	Effect()
abstract State	eventHandler(State state, Event event) Apply the event to the state.
Effect<Event,State>	eventTrigger(ReplicatedEntity.EventTriggerContext ctx, State state, Event event) Side effects from the event handler are generally discouraged, but for some use cases you may need to trigger side effects after consuming replicated events and then this method can be implemented.
abstract State	initialState() Abstract method that must be implemented by concrete subclass to define the initial state of the entity.
State	internalApplyEvent(State state, Event event) INTERNAL API
CommandHandlerImpl<Command,Event,State>	internalCommandHandler() INTERNAL API
EffectImpl<Event,State>	internalEventTrigger(EventTriggerContextImpl ctx, State state, Event event) INTERNAL API
EffectImpl<Event,State>	internalRecoveryCompleted(ReplicatedActorContextImpl ctx, State state) INTERNAL API
scala.collection.immutable.Set<java.lang.String>	internalTagsFor(EventTaggingContextImpl ctx, Event event) INTERNAL API
static <Command,Event,State> akka.actor.Props	props(java.lang.String persistenceIdPrefix, java.lang.String entityId, scala.Function0<ReplicatedEntity<Command,Event,State>> entityFactory, PersistenceMultiDcSettings settings, scala.reflect.ClassTag<Command> evidence$2) The Props for the actor that can run a ReplicatedEntity.
Effect<Event,State>	recoveryCompleted(ReplicatedEntity.ActorContext ctx, State state) This method is called to notify the entity that the recovery process is finished.
scala.collection.immutable.Set<java.lang.String>	tagsFor(ReplicatedEntity.EventTaggingContext ctx, Event event) Advanced version of tagsFor(Event) carrying additional contextual information about the event.

Methods inherited from class akka.persistence.multidc.internal.InternalReplicatedEntity

allDcs, currentTimeMillis, entityId, getEntityId, getSelf, getSelfDc, internalSetEntityId, internalSetLogger, internalSetSelf, internalSetSelfDc, log, otherDcs, persistenceId, postStop, replicatedEventHandler, self, selfDc, selfEventHandler, snapshotMigration, supervisorStrategy

Methods inherited from class java.lang.Object

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

Constructor Detail

ReplicatedEntity

public ReplicatedEntity()

Method Detail

props

public static <Command,Event,State> akka.actor.Props props(java.lang.String persistenceIdPrefix,
                                                           java.lang.String entityId,
                                                           scala.Function0<ReplicatedEntity<Command,Event,State>> entityFactory,
                                                           PersistenceMultiDcSettings settings,
                                                           scala.reflect.ClassTag<Command> evidence$2)

The Props for the actor that can run a ReplicatedEntity.

Use clusterShardingProps(java.lang.String, scala.Function0<akka.persistence.multidc.scaladsl.ReplicatedEntity<Command, Event, State>>, akka.persistence.multidc.PersistenceMultiDcSettings, scala.reflect.ClassTag<Command>) instead when using Cluster Sharding.

Parameters:

persistenceIdPrefix - Prefix for the persistenceId, which is concatenated with the entityId and the data center identifier. Empty string is a valid prefix if the entityId itself is globally unique. Note that this can't be changed, since it is part of the storage key (persistenceId).

entityId - The identifier of the entity. The persistenceId includes this entityId and is concatenated with persistenceIdPrefix and the data center identifier.

entityFactory - Factory for creating a new instance of the entity. It has to be a factory so that a new instance is created in case the actor is restarted.

settings - Configuration settings.

evidence$2 - (undocumented)

Returns:

(undocumented)

clusterShardingProps

public static <Command,Event,State> akka.actor.Props clusterShardingProps(java.lang.String entityTypeName,
                                                                          scala.Function0<ReplicatedEntity<Command,Event,State>> entityFactory,
                                                                          PersistenceMultiDcSettings settings,
                                                                          scala.reflect.ClassTag<Command> evidence$3)

The Props for the actor that can run a ReplicatedEntity with Cluster Sharding.

Parameters:

entityTypeName - Use the same as the entity type name in Cluster Sharding. It is a prefix for the persistenceId, which is concatenated with the entityId and the data center identifier. Note that this can't be changed, since it is part of the storage key (persistenceId).

entityFactory - Factory for creating a new instance of the entity. It has to be a factory so that a new instance is created in case the actor is restarted.

settings - Configuration settings.

evidence$3 - (undocumented)

Returns:

(undocumented)

CommandHandler

protected final ReplicatedEntity.CommandHandlerFactories<Command,Event,State> CommandHandler()

Effect

protected final EffectFactories<Command,Event,State> Effect()

initialState

public abstract State initialState()

Abstract method that must be implemented by concrete subclass to define the initial state of the entity.

Specified by:

initialState in class InternalReplicatedEntity<Command,Event,State>

Returns:

(undocumented)

commandHandler

public abstract ReplicatedEntity.CommandHandler<Command,Event,State> commandHandler()

Abstract method that must be implemented by concrete subclass to define the command handlers of the entity. CommandHandler defines command handlers and optional functions for other signals, e.g. Termination messages if watch is used.

Note that you can have different handlers based on current state by using CommandHandler.byState.

Returns:

(undocumented)

eventHandler

public abstract State eventHandler(State state,
                                   Event event)

Apply the event to the state. Return the new State.

Parameters:

state - (undocumented)

event - (undocumented)

Returns:

(undocumented)

recoveryCompleted

public Effect<Event,State> recoveryCompleted(ReplicatedEntity.ActorContext ctx,
                                             State state)

This method is called to notify the entity that the recovery process is finished.

The returned Effect will be applied immediately, in the same way it would be in a CommandHandler. More often than not returning a simple Effect.none is what would be done in this hook, however any other effect is also valid, including persisting events to signify a successful recovery.

Parameters:

ctx - (undocumented)

state - (undocumented)

Returns:

(undocumented)

tagsFor

public scala.collection.immutable.Set<java.lang.String> tagsFor(ReplicatedEntity.EventTaggingContext ctx,
                                                                Event event)

Advanced version of tagsFor(Event) carrying additional contextual information about the event. Allows adding adding tags to the persisted event, along will information where the event originated (if it originated in this Dc, or was it replicated to this Dc).

Tags can be useful during reconstruction of a read side, using persistence queries like eventsByTag.

Invoked before passing an to-be-persisted Event to the underlying journal.

WARNING: Make sure to override only one of the overloads of tagsFor to avoid confusion.

Parameters:

ctx - (undocumented)

event - (undocumented)

Returns:

(undocumented)

eventTrigger

public Effect<Event,State> eventTrigger(ReplicatedEntity.EventTriggerContext ctx,
                                        State state,
                                        Event event)

Side effects from the event handler are generally discouraged, but for some use cases you may need to trigger side effects after consuming replicated events and then this method can be implemented. It is called for all events, but it is not called during recovery. Side effects after recovery should be done in recoveryCompleted(akka.persistence.multidc.scaladsl.ReplicatedEntity.ActorContext, State) based on the state.

Parameters:

ctx - The context contains information about which DC the event was originally persisted in, and access to the ordinary ReplicatedEntity.ActorContext.

state - Current state, after the event was applied.

event - The event that was consumed.

Returns:

Effect, for example persisting new event.

internalEventTrigger

public EffectImpl<Event,State> internalEventTrigger(EventTriggerContextImpl ctx,
                                                    State state,
                                                    Event event)

INTERNAL API

Specified by:

internalEventTrigger in class InternalReplicatedEntity<Command,Event,State>

Parameters:

ctx - (undocumented)

state - (undocumented)

event - (undocumented)

Returns:

(undocumented)

internalTagsFor

public final scala.collection.immutable.Set<java.lang.String> internalTagsFor(EventTaggingContextImpl ctx,
                                                                              Event event)

INTERNAL API

Specified by:

internalTagsFor in class InternalReplicatedEntity<Command,Event,State>

Parameters:

ctx - (undocumented)

event - (undocumented)

Returns:

(undocumented)

internalApplyEvent

public final State internalApplyEvent(State state,
                                      Event event)

INTERNAL API

Specified by:

internalApplyEvent in class InternalReplicatedEntity<Command,Event,State>

Parameters:

state - (undocumented)

event - (undocumented)

Returns:

(undocumented)

internalCommandHandler

public final CommandHandlerImpl<Command,Event,State> internalCommandHandler()

INTERNAL API

Specified by:

internalCommandHandler in class InternalReplicatedEntity<Command,Event,State>

Returns:

(undocumented)

internalRecoveryCompleted

public final EffectImpl<Event,State> internalRecoveryCompleted(ReplicatedActorContextImpl ctx,
                                                               State state)

INTERNAL API

Specified by:

internalRecoveryCompleted in class InternalReplicatedEntity<Command,Event,State>

Parameters:

ctx - (undocumented)

state - (undocumented)

Returns:

(undocumented)