Package kalix.javasdk.eventsourcedentity

Class EventSourcedEntity<S,E>

Object
kalix.javasdk.eventsourcedentity.EventSourcedEntity<S,E>
Type Parameters:
S - The type of the state for this entity.
E - The parent type of the event hierarchy for this entity.
public abstract class EventSourcedEntity<S,E> extends Object
The Event Sourced state model captures changes to data by storing events in a journal. The current entity state is derived from the emitted events.

When implementing an Event Sourced Entity, you first define what will be its internal state (your domain model), the commands it will handle and the events it will emit to modify its state.

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

  • emit events and build a reply
  • directly returning to the caller if the command is not requesting any state change
  • rejected the command by returning an error
  • instruct Kalix to delete the entity

Each event is handled by an event handler method and should return an updated state for the entity.

  • Constructor Details

    • EventSourcedEntity

      public EventSourcedEntity()

  • Method Details

    • emptyState

      public S emptyState()
      Implement by returning the initial empty state object. This object will be passed into the command and event 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 or event handler.

    • _internalSetCommandContext

      public void _internalSetCommandContext(Optional<CommandContext> context)
      INTERNAL API

    • eventContext

      protected final EventContext eventContext()
      Additional context and metadata for an event handler.

      It will throw an exception if accessed from constructor or command handler.

    • _internalSetEventContext

      public void _internalSetEventContext(Optional<EventContext> context)
      INTERNAL API

    • _internalSetCurrentState

      public void _internalSetCurrentState(S state)
      INTERNAL API

    • currentState

      @ApiMayChange protected final S currentState()
      Returns the state as currently stored by Kalix.

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

      This method can only be called when handling a command or an event. 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 EventSourcedEntity.Effect.Builder<S,E> effects()