ReplicatedEntity

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.

Command: the super type of all commands
Event: the super type of all events
State: the type of the state

Annotations: @ApiMayChange()

Linear Supertypes

InternalReplicatedEntity[Command, Event, State], AnyRef, Any

Type Hierarchy

Instance Constructors

new ReplicatedEntity()

Abstract Value Members

abstract def commandHandler(): CommandHandler[Command, Event, State]

Abstract method that must be implemented by concrete subclass to define the command handlers of the entity.
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 and #byStateCommandHandlerBuilder
abstract def eventHandler(): EventHandler[Event, State]

Abstract method that must be implemented by concrete subclass to define the event handlers of the entity.
Abstract method that must be implemented by concrete subclass to define the event handlers of the entity.
Can be created through a #eventHandlerBuilder or a lambda.
abstract def initialState: State

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

Definition Classes
ReplicatedEntity → InternalReplicatedEntity

Concrete Value Members

final def !=(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def ##(): Int

Definition Classes
AnyRef → Any
def +(other: String): String

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to any2stringadd[ReplicatedEntity[Command, Event, State]] performed by method any2stringadd in scala.Predef.
Definition Classes
any2stringadd
def ->[B](y: B): (ReplicatedEntity[Command, Event, State], B)

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to ArrowAssoc[ReplicatedEntity[Command, Event, State]] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc
Annotations
@inline()
final def ==(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def Effect: EffectFactories[Command, Event, State]
final def allDcs: Set[String]

All data centers
All data centers

Attributes
protected
Definition Classes
InternalReplicatedEntity
final def asInstanceOf[T0]: T0

Definition Classes
Any
final def byStateCommandHandlerBuilder(rootStateClass: Class[State]): ByStateCommandHandlerBuilder[Command, Event, State]

returns
A new, mutable, builder for defining different command handling depending on the current state of the ReplicatedEntity.
def clone(): AnyRef

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( ... )
final def commandHandlerBuilder(commandClass: Class[Command]): CommandHandlerBuilder[Command, Event, State]

returns
A new, mutable, builder
def currentTimeMillis(): Long

Called to create the timestamp when an event is persisted.
Called to create the timestamp when an event is persisted. May be overridden if you want to use another clock source, or for testing purposes.

Definition Classes
InternalReplicatedEntity
def ensuring(cond: (ReplicatedEntity[Command, Event, State]) ⇒ Boolean, msg: ⇒ Any): ReplicatedEntity[Command, Event, State]

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to Ensuring[ReplicatedEntity[Command, Event, State]] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
def ensuring(cond: (ReplicatedEntity[Command, Event, State]) ⇒ Boolean): ReplicatedEntity[Command, Event, State]

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to Ensuring[ReplicatedEntity[Command, Event, State]] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
def ensuring(cond: Boolean, msg: ⇒ Any): ReplicatedEntity[Command, Event, State]

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to Ensuring[ReplicatedEntity[Command, Event, State]] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
def ensuring(cond: Boolean): ReplicatedEntity[Command, Event, State]

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to Ensuring[ReplicatedEntity[Command, Event, State]] performed by method Ensuring in scala.Predef.
Definition Classes
Ensuring
final def entityId: String

The id of the current entity
The id of the current entity

Attributes
protected
Definition Classes
InternalReplicatedEntity
final def eq(arg0: AnyRef): Boolean

Definition Classes
AnyRef
def equals(arg0: Any): Boolean

Definition Classes
AnyRef → Any
final def eventHandlerBuilder(rootEventClass: Class[Event]): EventHandlerBuilder[Event, State]

returns
A builder for creating the event handler
def eventTrigger(ctx: EventTriggerContext, state: State, event: Event): Effect[Event, State]

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.
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 based on the state.
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.
def finalize(): Unit

Attributes
protected[java.lang]
Definition Classes
AnyRef
Annotations
@throws( classOf[java.lang.Throwable] )
def formatted(fmtstr: String): String

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to StringFormat[ReplicatedEntity[Command, Event, State]] performed by method StringFormat in scala.Predef.
Definition Classes
StringFormat
Annotations
@inline()
final def getAllDcs(): Set[String]

All data centers
All data centers

Attributes
protected
final def getClass(): Class[_]

Definition Classes
AnyRef → Any
final def getEntityId(): String

The id of the current entity
The id of the current entity

Attributes
protected
Definition Classes
InternalReplicatedEntity
final def getOtherDcs(): Set[String]

Other data centers, allDcs without selfDc
Other data centers, allDcs without selfDc

Attributes
protected
def getSelf(): ActorRef

The 'self' field holds the ActorRef for this actor.
The 'self' field holds the ActorRef for this actor.
Can be used to send messages to itself:
```
self ! message
```
Used as the implicit sender for !
Definition Classes
InternalReplicatedEntity
final def getSelfDc(): String

Java API: Name of the data-center in which this entity is running
Java API: Name of the data-center in which this entity is running

Attributes
protected
Definition Classes
InternalReplicatedEntity
def hashCode(): Int

Definition Classes
AnyRef → Any
final def internalRecoveryCompleted(ctx: ReplicatedActorContextImpl, state: State): EffectImpl[Event, State]

INTERNAL API
INTERNAL API

Definition Classes
ReplicatedEntity → InternalReplicatedEntity
Annotations
@InternalApi()
final def isInstanceOf[T0]: Boolean

Definition Classes
Any
def log: ReplicatedEntityLoggingAdapter

Special akka.event.LoggingAdapter which adds the enclosing replicated entity persistenceId to each log statement.
Special akka.event.LoggingAdapter which adds the enclosing replicated entity persistenceId to each log statement. Configure how it should add such metadata under the akka.persistence.multi-datacenter.logging config section.
WARNING: The logger may only be used after construction of the ReplicatedEntity has completed, i.e. not in its constructor.
WARNING: When using the MDC features of this logger, and NOT using Lightbend Monitoring's automatic MDC propagation, be awere that the MDC context would be lost if the logger were to be invoked from a Future.

Definition Classes
InternalReplicatedEntity
final def ne(arg0: AnyRef): Boolean

Definition Classes
AnyRef
final def notify(): Unit

Definition Classes
AnyRef
final def notifyAll(): Unit

Definition Classes
AnyRef
final lazy val otherDcs: Set[String]

Other data centers, allDcs without selfDc
Other data centers, allDcs without selfDc

Attributes
protected
Definition Classes
InternalReplicatedEntity
def persistenceId(persistenceIdPrefix: String, entityId: String, dc: String): String

When migrating from PersistenceActor you need to define the exact format of the persistenceId to match the old identifiers in one of the data centers, which hosts the old data which are stored with persistence ids that don't include the data center suffix.
When migrating from PersistenceActor you need to define the exact format of the persistenceId to match the old identifiers in one of the data centers, which hosts the old data which are stored with persistence ids that don't include the data center suffix. The prefix and separator is probably also different for old persistenceId.
The persistenceId is by default the concatenation of persistenceIdPrefix, entityId and the data center identifier, separated with |.

Definition Classes
InternalReplicatedEntity
def postStop(): Unit

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

Definition Classes
InternalReplicatedEntity
Annotations
@InternalApi() @throws( classOf[Exception] )
def recoveryCompleted(ctx: ActorContext, state: State): Effect[Event, State]

This method is called to notify the entity that the recovery process is finished.
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.
def replicatedEventHandler(ctx: ReplicatedEventContext, state: State, event: Event): State

Apply the event that was persisted by another data center to the given state.
Apply the event that was persisted by another data center to the given state. Return the new State. By default this invokes eventHandler but in case more context of the event is needed this can be overridden instead. See also #selfEventHandler.

Definition Classes
InternalReplicatedEntity
implicit def self: ActorRef

The 'self' field holds the ActorRef for this actor.
The 'self' field holds the ActorRef for this actor.
Can be used to send messages to itself:
```
self ! message
```
Used as the implicit sender for !
Definition Classes
InternalReplicatedEntity
final def selfDc: String

Name of the data-center in which this entity is running
Name of the data-center in which this entity is running

Attributes
protected
Definition Classes
InternalReplicatedEntity
def selfEventHandler(ctx: SelfEventContext, state: State, event: Event): State

Apply the event that was persisted by this data center to the given state.
Apply the event that was persisted by this data center to the given state. Return the new State. By default this invokes eventHandler but in case more context of the event is needed this can be overridden instead. See also #replicatedEventHandler.

Definition Classes
InternalReplicatedEntity
def snapshotMigration(oldSnapshot: Any): State

When migrating from PersistentActor to Replicated entity this method is called to be able to convert old snapshots to the new State if needed.
When migrating from PersistentActor to Replicated entity this method is called to be able to convert old snapshots to the new State if needed. By default it tries to cast the oldSnapshot to State.

Definition Classes
InternalReplicatedEntity
def supervisorStrategy: SupervisorStrategy

User overridable definition the strategy to use for supervising child actors.
User overridable definition the strategy to use for supervising child actors.

Definition Classes
InternalReplicatedEntity
final def synchronized[T0](arg0: ⇒ T0): T0

Definition Classes
AnyRef
def tagsFor(ctx: EventTaggingContext, event: Event): Set[String]

Advanced version of tagsFor(Event) carrying additional contextual information about the 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.
def tagsFor(event: Event): Set[String]

Allows adding tags to the persisted 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.
def toString(): String

Definition Classes
AnyRef → Any
final def wait(): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long, arg1: Int): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
final def wait(arg0: Long): Unit

Definition Classes
AnyRef
Annotations
@throws( ... )
def →[B](y: B): (ReplicatedEntity[Command, Event, State], B)

Implicit information
This member is added by an implicit conversion from ReplicatedEntity[Command, Event, State] to ArrowAssoc[ReplicatedEntity[Command, Event, State]] performed by method ArrowAssoc in scala.Predef.
Definition Classes
ArrowAssoc

Related Docs: object ReplicatedEntity | package javadsl

abstract class ReplicatedEntity[Command, Event, State >: Null] extends InternalReplicatedEntity[Command, Event, State]

Instance Constructors

new ReplicatedEntity()

Abstract Value Members

abstract def commandHandler(): CommandHandler[Command, Event, State]

abstract def eventHandler(): EventHandler[Event, State]

abstract def initialState: State

Concrete Value Members

final def !=(arg0: Any): Boolean

final def ##(): Int

def +(other: String): String

def ->[B](y: B): (ReplicatedEntity[Command, Event, State], B)

final def ==(arg0: Any): Boolean

final def Effect: EffectFactories[Command, Event, State]

final def allDcs: Set[String]

final def asInstanceOf[T0]: T0

final def byStateCommandHandlerBuilder(rootStateClass: Class[State]): ByStateCommandHandlerBuilder[Command, Event, State]

def clone(): AnyRef

final def commandHandlerBuilder(commandClass: Class[Command]): CommandHandlerBuilder[Command, Event, State]

def currentTimeMillis(): Long

def ensuring(cond: (ReplicatedEntity[Command, Event, State]) ⇒ Boolean, msg: ⇒ Any): ReplicatedEntity[Command, Event, State]

def ensuring(cond: (ReplicatedEntity[Command, Event, State]) ⇒ Boolean): ReplicatedEntity[Command, Event, State]

def ensuring(cond: Boolean, msg: ⇒ Any): ReplicatedEntity[Command, Event, State]

def ensuring(cond: Boolean): ReplicatedEntity[Command, Event, State]

final def entityId: String

final def eq(arg0: AnyRef): Boolean

def equals(arg0: Any): Boolean

final def eventHandlerBuilder(rootEventClass: Class[Event]): EventHandlerBuilder[Event, State]

def eventTrigger(ctx: EventTriggerContext, state: State, event: Event): Effect[Event, State]

def finalize(): Unit

def formatted(fmtstr: String): String

final def getAllDcs(): Set[String]

final def getClass(): Class[_]

final def getEntityId(): String

final def getOtherDcs(): Set[String]

def getSelf(): ActorRef

final def getSelfDc(): String

def hashCode(): Int

final def internalRecoveryCompleted(ctx: ReplicatedActorContextImpl, state: State): EffectImpl[Event, State]

final def isInstanceOf[T0]: Boolean

def log: ReplicatedEntityLoggingAdapter

final def ne(arg0: AnyRef): Boolean

final def notify(): Unit

final def notifyAll(): Unit

final lazy val otherDcs: Set[String]

def persistenceId(persistenceIdPrefix: String, entityId: String, dc: String): String

def postStop(): Unit

def recoveryCompleted(ctx: ActorContext, state: State): Effect[Event, State]

def replicatedEventHandler(ctx: ReplicatedEventContext, state: State, event: Event): State

implicit def self: ActorRef

final def selfDc: String

def selfEventHandler(ctx: SelfEventContext, state: State, event: Event): State

def snapshotMigration(oldSnapshot: Any): State

def supervisorStrategy: SupervisorStrategy

final def synchronized[T0](arg0: ⇒ T0): T0

def tagsFor(ctx: EventTaggingContext, event: Event): Set[String]

def tagsFor(event: Event): Set[String]

def toString(): String

final def wait(): Unit

final def wait(arg0: Long, arg1: Int): Unit

final def wait(arg0: Long): Unit

def →[B](y: B): (ReplicatedEntity[Command, Event, State], B)

Inherited from InternalReplicatedEntity[Command, Event, State]

Inherited from AnyRef

Inherited from Any

Inherited by implicit conversion any2stringadd from ReplicatedEntity[Command, Event, State] to any2stringadd[ReplicatedEntity[Command, Event, State]]

Inherited by implicit conversion StringFormat from ReplicatedEntity[Command, Event, State] to StringFormat[ReplicatedEntity[Command, Event, State]]

Inherited by implicit conversion Ensuring from ReplicatedEntity[Command, Event, State] to Ensuring[ReplicatedEntity[Command, Event, State]]

Inherited by implicit conversion ArrowAssoc from ReplicatedEntity[Command, Event, State] to ArrowAssoc[ReplicatedEntity[Command, Event, State]]

Ungrouped