PersistentEntity (Lagom Services API)

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

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

Constructors
Constructor and Description

PersistentEntity()

Constructors
Constructor and Description
`PersistentEntity()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
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.
`void`	`onUnhandledCommand(Command command, PersistentEntity.ReadOnlyCommandContext<Void> context)` This method is called if a command is not handled.
`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.
  - onUnhandledCommand
```
public void onUnhandledCommand(Command command,
                               PersistentEntity.ReadOnlyCommandContext<Void> context)
```
    This method is called if a command is not handled. It can be overridden for custom handling. By default it sends back an PersistentEntity.UnhandledCommandException via context.commandFailed.
    
    Parameters:
    
    command - the command that was not handled
    
    context - the context, for access to for example commandFailed
  - newBehavior
```
public final PersistentEntity.Behavior newBehavior(State state)
```
    Create a new empty Behavior with a given state.
  - newBehaviorBuilder
```
public final PersistentEntity.BehaviorBuilder newBehaviorBuilder(State state)
```
    Create a new empty BehaviorBuilder with a given state.

Class PersistentEntity<Command,Event,State>

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class Object

Constructor Detail

PersistentEntity

Method Detail

internalSetEntityId

behavior

internalSetCurrentBehavior

entityTypeName

initialBehavior

recoveryCompleted

onUnhandledCommand

newBehavior

newBehaviorBuilder