com.lightbend.lagom.javadsl.persistence

Class PersistentEntity<Command,Event,State>

Object

com.lightbend.lagom.javadsl.persistence.PersistentEntity<Command,Event,State>

public abstract class PersistentEntity<Command,Event,State>
extends Object

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

Nested Class Summary

Nested Classes

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.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$
static interface	PersistentEntity.PersistNone<B extends Event> INTERNAL API
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 Summary

Constructors

Constructor and Description
PersistentEntity()

Method Summary

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.
com.lightbend.lagom.javadsl.persistence.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.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PersistentEntity

public PersistentEntity()

Method Detail

internalSetEntityId

public void internalSetEntityId(String id)

INTERNAL API

behavior

public final PersistentEntity.Behavior behavior()

internalSetCurrentBehavior

public void internalSetCurrentBehavior(PersistentEntity.Behavior b)

INTERNAL API

entityTypeName

public String entityTypeName()

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

initialBehavior

public abstract PersistentEntity.Behavior initialBehavior(Optional<State> snapshotState)

Abstract method that must be implemented by concrete subclass to define the behavior of the entity. Use newBehaviorBuilder(State) to create a mutable builder for defining the behavior.

recoveryCompleted

public PersistentEntity.Behavior recoveryCompleted()

This method is called to notify the entity that the recovery process is finished.

newBehavior

public final PersistentEntity.Behavior newBehavior(State state)

Create a new empty Behavior with a given state.

newBehaviorBuilder

public final com.lightbend.lagom.javadsl.persistence.PersistentEntity.BehaviorBuilder newBehaviorBuilder(State state)

Create a new empty BehaviorBuilder with a given state.