A persistent actor durably records state changes as events instead of replacing one mutable state value. Its journal grows by appending events, allowing the actor to recover its latest state after a restart by replaying that history. section 9.2
A persistent actor processes state changes through four cooperating parts:
- A unique persistenceId identifies the actor’s durable history. section 9.2.1
- The command handler validates a command against current state and produces an event effect. section 9.2 section 9.2.1
- The event handler applies each event to produce the next state. section 9.2.1
- Recovery reads the journal and replays events until the last known state is reconstructed. section 9.2
Cargo container
A container actor can define AddCargo and GetCargos commands, a CargoAdded event, and State(cargos: List[Cargo] = Nil). AddCargo persists CargoAdded; the event handler adds the cargo to state, while GetCargos reads the recovered list. section 9.2.1
Recovery flow diagram showing how a persistent actor reconstructs state from its journal. section 9.2
Clustered deployments combine persistence with Akka Sharding. An EntityTypeKey is incorporated into the persistence ID so entities with the same local identifier remain distinguishable across entity types and cluster nodes. section 9.2.2
