An event records something that happened. In a persistent actor, it is the accepted output of handling a command: the actor validates the intended change, generates an event, and appends it to a journal instead of replacing a single stored state value. The journal preserves the actor’s complete history. section 9.2
Follow the transition from an incoming command, through validation, to an event stored as a journal entry. section 9.2
Events also act as asynchronous notifications. A Conversation actor can publish that it added a message without knowing which components care. Subscribers such as mentions handling can react later, and connected browsers can receive a direct notification rather than repeatedly polling. section 1.5.2 section 1.5.3
Publishing events separates components in three practical ways:
- It removes direct knowledge of subscribers: the publisher reports an occurrence and continues working. section 1.5.2 section 1.5.3
- It tolerates delayed handling: subscribers can receive events later, as long as they eventually receive them. section 1.5.3
- It isolates failures and location: conversations can continue while subscribers restart, even when components run on different servers. section 1.5.3
Container cargo history
Model a container with AddCargo as a command, CargoAdded as an event, and a State holding its cargo list. An EventSourcedBehavior uses a command handler to choose an Effect and event, then an event handler to derive the next state. On restart, replaying stored CargoAdded events reconstructs the container’s last known state. section 9.2 section 9.2.1
A persistent event is therefore both history and recovery input: restarting does not require a separately updated current-state record, because the actor reads its journal and replays events. In clustered use, persistent actor identity must be unique; Akka Sharding can combine entity identity with a type key to prevent collisions across nodes or entity types. section 9.2 section 9.2.1
