Package akka.javasdk.keyvalueentity

Class KeyValueEntity<S>

Object
akka.javasdk.keyvalueentity.KeyValueEntity<S>
Type Parameters:
S - The type of the state for this entity.
public abstract class KeyValueEntity<S> extends Object
Key Value Entities persist their state on every change. You can think of them as a Key-Value entity where the key is the entity id and the value is the state of the entity.

When implementing a Key Value Entity, you first define what will be its internal state (your domain model), and the commands it will handle (mutation requests).

Each command is handled by a command handler. Command handlers are methods returning an KeyValueEntity.Effect. When handling a command, you use the Effect API to:

  • update the entity state and send a reply to the caller
  • directly reply to the caller if the command is not requesting any state change
  • rejected the command by returning an error
  • instruct the runtime to delete the entity

Concrete classes can accept the following types to the constructor:

Concrete class must be annotated with ComponentId.

  • Constructor Details

    • KeyValueEntity

      public KeyValueEntity()

  • Method Details

    • emptyState

      public S emptyState()
      Implement by returning the initial empty state object. This object will be passed into the command handlers, until a new state replaces it.

      Also known as "zero state" or "neutral state".

      The default implementation of this method returns null. It can be overridden to return a more sensible initial state.

    • commandContext

      protected final CommandContext commandContext()
      Additional context and metadata for a command handler.

      It will throw an exception if accessed from constructor.

      Throws:
      IllegalStateException - if accessed outside a handler method

    • currentState

      protected final S currentState()
      Returns the state as currently stored.

      Note that modifying the state directly will not update it in storage. To save the state, you must call {effects().updateState()}.

      This method can only be called when handling a command. Calling it outside a method (eg: in the constructor) will raise a IllegalStateException exception.

      Throws:
      IllegalStateException - if accessed outside a handler method

    • effects

      protected final KeyValueEntity.Effect.Builder<S> effects()