akka.persistence.multidc.javadsl

Class ReplicatedEntity<Command,Event,State>

java.lang.Object

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

akka.persistence.multidc.javadsl.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, commandHandler and eventHandler are abstract methods that your concrete subclass must implement.

The commandHandler defines how to process incoming commands, construct one using the builder returned by commandHandlerBuilder to use the same handler regardless of state or the byStateCommandHandlerBuilder to have different handling depending on state.

Persistent and replicated events are applied to the state with the eventHandler. Construct an event handler using the builder returned by eventHandlerBuilder.

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 class	ReplicatedEntity.CommandHandlers$ 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
ByStateCommandHandlerBuilder<Command,Event,State>	byStateCommandHandlerBuilder(java.lang.Class<State> rootStateClass)
static <Command,Event,State> akka.actor.Props	clusterShardingProps(java.lang.Class<Command> commandClass, java.lang.String entityTypeName, java.util.function.Supplier<ReplicatedEntity<Command,Event,State>> entityFactory, PersistenceMultiDcSettings settings) The Props for the actor that can run a ReplicatedEntity with Cluster Sharding.
abstract CommandHandler<Command,Event,State>	commandHandler() Abstract method that must be implemented by concrete subclass to define the command handlers of the entity.
CommandHandlerBuilder<Command,Event,State>	commandHandlerBuilder(java.lang.Class<Command> commandClass)
EffectFactories<Command,Event,State>	Effect()
abstract EventHandler<Event,State>	eventHandler() Abstract method that must be implemented by concrete subclass to define the event handlers of the entity.
EventHandlerBuilder<Event,State>	eventHandlerBuilder(java.lang.Class<Event> rootEventClass)
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.
protected java.util.Set<java.lang.String>	getAllDcs() All data centers
protected java.util.Set<java.lang.String>	getOtherDcs() Other data centers, allDcs without selfDc
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) Apply the event to the state.
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.Class<Command> commandClass, java.lang.String persistenceIdPrefix, java.lang.String entityId, java.util.function.Supplier<ReplicatedEntity<Command,Event,State>> entityFactory, PersistenceMultiDcSettings settings) 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.
java.util.Set<java.lang.String>	tagsFor(Event event) Allows adding tags to the persisted event.
java.util.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.Class<Command> commandClass,
                                                           java.lang.String persistenceIdPrefix,
                                                           java.lang.String entityId,
                                                           java.util.function.Supplier<ReplicatedEntity<Command,Event,State>> entityFactory,
                                                           PersistenceMultiDcSettings settings)

The Props for the actor that can run a ReplicatedEntity.

Use clusterShardingProps(java.lang.Class<Command>, java.lang.String, java.util.function.Supplier<akka.persistence.multidc.javadsl.ReplicatedEntity<Command, Event, State>>, akka.persistence.multidc.PersistenceMultiDcSettings) 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.

commandClass - (undocumented)

Returns:

(undocumented)

clusterShardingProps

public static <Command,Event,State> akka.actor.Props clusterShardingProps(java.lang.Class<Command> commandClass,
                                                                          java.lang.String entityTypeName,
                                                                          java.util.function.Supplier<ReplicatedEntity<Command,Event,State>> entityFactory,
                                                                          PersistenceMultiDcSettings settings)

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.

commandClass - (undocumented)

Returns:

(undocumented)

Effect

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

byStateCommandHandlerBuilder

public final ByStateCommandHandlerBuilder<Command,Event,State> byStateCommandHandlerBuilder(java.lang.Class<State> rootStateClass)

Parameters:

rootStateClass - (undocumented)

Returns:

A new, mutable, builder for defining different command handling depending on the current state of the ReplicatedEntity.

commandHandlerBuilder

public final CommandHandlerBuilder<Command,Event,State> commandHandlerBuilder(java.lang.Class<Command> commandClass)

Parameters:

commandClass - (undocumented)

Returns:

A new, mutable, builder

getAllDcs

protected final java.util.Set<java.lang.String> getAllDcs()

All data centers

Returns:

(undocumented)

getOtherDcs

protected final java.util.Set<java.lang.String> getOtherDcs()

Other data centers, allDcs without selfDc

Returns:

(undocumented)

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

To create a CommandHandler use one of the two builders commandHandlerBuilder(java.lang.Class<Command>) and byStateCommandHandlerBuilder(java.lang.Class<State>)

Returns:

(undocumented)

eventHandler

public abstract EventHandler<Event,State> eventHandler()

Abstract method that must be implemented by concrete subclass to define the event handlers of the entity.

Can be created through a eventHandlerBuilder(java.lang.Class<Event>) or a lambda.

Returns:

(undocumented)

eventHandlerBuilder

public final EventHandlerBuilder<Event,State> eventHandlerBuilder(java.lang.Class<Event> rootEventClass)

Parameters:

rootEventClass - (undocumented)

Returns:

A builder for creating the event handler

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 java.util.Set<java.lang.String> tagsFor(Event event)

Allows adding tags to the persisted event. 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.

Parameters:

event - (undocumented)

Returns:

(undocumented)

tagsFor

public java.util.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. 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.

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.javadsl.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)

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

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)