com.lightbend.lagom.javadsl.persistence
Behavior consists of current state and functions to process incoming commands and persisted events.
Behavior consists of current state and functions to process incoming commands
and persisted events. Behavior
is an immutable class. Use the mutable BehaviorBuilder
for defining command and event handlers.
Mutable builder that is used for defining the event and command handlers.
Mutable builder that is used for defining the event and command handlers. Use [#build] to create the immutable Behavior.
The context that is passed to command handler function.
A command handler returns a Persist
directive that defines what event or events,
if any, to persist.
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.
The context that is passed to read-only command handlers.
Abstract method that must be implemented by concrete subclass to define the behavior of the entity.
Abstract method that must be implemented by concrete subclass to define the behavior of the entity. Use #newBehaviorBuilder to create a mutable builder for defining the behavior.
The name of this entity type.
The name of this entity type. It should be unique among the entity
types of the service. By default it is using the short class name
of the concrete 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
).
Create a new empty Behavior
with a given state.
Create a new empty BehaviorBuilder
with a given state.
This method is called to notify the entity that the recovery process is finished.
Current state of the entity.
Current state of the entity. Typically accessed from event and command handlers.
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 theBehavior
of the entity. The behavior consists of current state and functions to process incoming commands and persisted events.The
PersistentEntity
receives commands of typeCommand
that can be validated before persisting state changes as events of typeEvent
. The functions that process incoming commands are registered in theBehavior
usingsetCommandHandler
of theBehaviorBuilder
.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 theBehaviorBuilder
. Replies are sent with thereply
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 thethenPersist
,thenPersistAll
ordone
methods of the context that is passed to the command handler function to create thePersist
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 thesetEventHandler
method of theBehaviorBuilder
. 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 thestate
method of thePersistentEntity
. 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 thePersist
directive. A typical side effect is to reply to the request to confirm that it was performed successfully. Replies are sent with thereply
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 theBehaviorBuilder
. Such an event handler returns the newBehavior
instead of just returning the new state. You can access current behavior with thebehavior
method of thePersistentEntity
and using thebuilder
method of theBehavior
.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 returnedBehavior
. One thing to keep in mind is that if you are using event handlers that change the behavior (setEventHandlerChangingBehavior
) you must also restore correspondingBehavior
from the snapshot state that is passed as a parameter to theinitialBehavior
method.Type parameter
Command
: the super type of all commands, must implement PersistentEntity.ReplyType to define the reply type of each command type Type parameterEvent
: the super type of all events Type parameterState
: the type of the state