public abstract class PersistentEntity<Command,Event,State> extends Object
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 command handlers may emit zero, one or many events. When many events are emitted, they are stored atomically and in the same order they were emitted. Only after persisting all the events external side effects will be performed.
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
| Modifier and Type | Class and Description |
|---|---|
class |
PersistentEntity.Behavior
Behavior consists of current state and functions to process incoming commands
and persisted events.
|
class |
PersistentEntity.Behavior$ |
class |
PersistentEntity.BehaviorBuilder
Mutable builder that is used for defining the event and command handlers.
|
class |
PersistentEntity.CommandContext<R>
The context that is passed to command handler function.
|
static class |
PersistentEntity.InvalidCommandException
Standard exception when rejecting invalid commands.
|
static class |
PersistentEntity.InvalidCommandException$ |
class |
PersistentEntity.Persist<B extends Event>
A command handler returns a
Persist directive that defines what event or events,
if any, to persist. |
class |
PersistentEntity.PersistAll<B extends Event>
INTERNAL API
|
class |
PersistentEntity.PersistAll$ |
static class |
PersistentEntity.PersistException
Exception that is used when persist fails.
|
static class |
PersistentEntity.PersistException$ |
class |
PersistentEntity.PersistNone<B extends Event>
INTERNAL API
|
class |
PersistentEntity.PersistNone$ |
class |
PersistentEntity.PersistOne<B extends Event>
INTERNAL API
|
class |
PersistentEntity.PersistOne$ |
class |
PersistentEntity.ReadOnlyCommandContext<R>
The context that is passed to read-only command handlers.
|
static interface |
PersistentEntity.ReplyType<R>
Commands to a
PersistentEntity must implement this interface
to define the reply type. |
static class |
PersistentEntity.UnhandledCommandException
Exception that is used when command is not handled
|
static class |
PersistentEntity.UnhandledCommandException$ |
| Constructor and Description |
|---|
PersistentEntity() |
| Modifier and Type | Method and Description |
|---|---|
PersistentEntity.Behavior |
behavior() |
String |
entityTypeName()
The name of this entity type.
|
abstract PersistentEntity.Behavior |
initialBehavior(Optional<State> snapshotState)
Abstract method that must be implemented by concrete subclass to define
the behavior of the entity.
|
void |
internalSetCurrentBehavior(PersistentEntity.Behavior b)
INTERNAL API
|
void |
internalSetEntityId(String id)
INTERNAL API
|
PersistentEntity.Behavior |
newBehavior(State state)
Create a new empty
Behavior with a given state. |
PersistentEntity.BehaviorBuilder |
newBehaviorBuilder(State state)
Create a new empty
BehaviorBuilder with a given state. |
PersistentEntity.Behavior |
recoveryCompleted()
This method is called to notify the entity that the recovery process
is finished.
|
public void internalSetEntityId(String id)
public final PersistentEntity.Behavior behavior()
public void internalSetCurrentBehavior(PersistentEntity.Behavior b)
public String entityTypeName()
PersistentEntity class. Subclass may override
to define other type names. It is needed to override and retain
the original name when the class name is changed because this name
is part of the key of the store data (it is part of the persistenceId
of the underlying PersistentActor).public abstract PersistentEntity.Behavior initialBehavior(Optional<State> snapshotState)
newBehaviorBuilder(State) to create a mutable builder
for defining the behavior.public PersistentEntity.Behavior recoveryCompleted()
public final PersistentEntity.Behavior newBehavior(State state)
Behavior with a given state.public final PersistentEntity.BehaviorBuilder newBehaviorBuilder(State state)
BehaviorBuilder with a given state.