The base type of PersistentEntity events may implement this interface to make the events available for read-side processing.
The base type of PersistentEntity events may return one of these to make the events available for sharded read-side processing.
The base type of PersistentEntity events may return one of these to make the events available for read-side processing.
The base type of PersistentEntity events may return one of these to make the events available for read-side processing.
The tag
should be unique among the event types of the service.
The class name can be used as tag
, but note that it is needed
to retain the original tag when the class name is changed because
the tag is part of the store event data.
Selects a tag for an event.
Selects a tag for an event.
Can either be a static tag, or a sharded tag generator.
Commands to PersistentEntity are wrapped in this envelope when sent via PersistentEntityRef (i.e.
Commands to PersistentEntity are wrapped in this envelope when sent via PersistentEntityRef (i.e. Cluster Sharding).
Users should normally not use this class, but it is public case for power users in case of integration with Cluster Sharding entities that are not implemented with PersistentEntity.
Guice module for the Persistence API.
A PersistentEntity
has a stable entity identifier, with which
it can be accessed from anywhere in the cluster.
A PersistentEntity
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.
initialBehavior
is an abstract method that your concrete subclass must implement.
It returns the Behavior
of the entity. The behavior consists of current state
and functions to process incoming commands and persisted events.
The PersistentEntity
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 Behavior
using setCommandHandler
of the
BehaviorBuilder
.
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 setReadOnlyCommandHandler
of the BehaviorBuilder
. Replies are sent with the reply
method of the context that
is passed to the command handler function.
A command handler returns a Persist
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 Persist
directive.
When an event has been persisted successfully the state of type State
is updated by
applying the event to the current state. The functions for updating the state are
registered with the setEventHandler
method of the BehaviorBuilder
.
The event handler returns the new state. The state must be immutable, so you return
a new instance of the state. Current state can be accessed from the event handler with
the state
method of the PersistentEntity
. 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 in the afterPersist
function that can be defined when creating the Persist
directive.
A typical side effect is to reply to the request to confirm that it was performed
successfully. Replies are sent with the reply
method of the context that is passed
to the command handler function.
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. This is useful when implementing finite state machine (FSM)
like entities. Event handlers that change the behavior are registered with the
setEventHandlerChangingBehavior
of the BehaviorBuilder
. Such an event handler
returns the new Behavior
instead of just returning the new state. You can
access current behavior with the behavior
method of the PersistentEntity
and using the builder
method of the Behavior
.
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.
The snapshot if any is passed as a parameter to the initialBehavior
method and
you should use that state as the state of the returned Behavior
.
One thing to keep in mind is that if you are using event handlers that change the
behavior (setEventHandlerChangingBehavior
) you must also restore corresponding
Behavior
from the snapshot state that is passed as a parameter to the initialBehavior
method.
Type parameter Command
:
the super type of all commands, must implement PersistentEntity.ReplyType
to define the reply type of each command type
Type parameter Event
:
the super type of all events
Type parameter State
:
the type of the state
Commands are sent to a PersistentEntity using a
PersistentEntityRef
.
Commands are sent to a PersistentEntity using a
PersistentEntityRef
. It is retrieved with PersistentEntityRegistry#refFor.
At system startup all PersistentEntity classes must be registered here with PersistentEntityRegistry#register.
At system startup all PersistentEntity classes must be registered here with PersistentEntityRegistry#register.
Later, PersistentEntityRef can be retrieved with PersistentEntityRegistry#refFor.
Commands are sent to a PersistentEntity using a PersistentEntityRef
.
The base type of PersistentEntity events may return one of these to make the events available for sharded read-side processing.
The
tag
should be unique among the event types of the service.The
numShards
should be stable and never change.The class name can be used as
tag
, but note that it is needed to retain the original tag when the class name is changed because the tag is part of the store event data.