Package kalix.javasdk.valueentity

Class ValueEntity<S>

Object
kalix.javasdk.valueentity.ValueEntity<S>
Type Parameters:
S - The type of the state for this entity.
public abstract class ValueEntity<S> extends Object
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.

Kalix Value Entities have nothing in common with the domain-driven design concept of Value Objects. The Value in the name refers to the direct modification of the entity's state. When implementing a 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 ValueEntity.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 Kalix to delete the entity

  • Constructor Details

    • ValueEntity

      public ValueEntity()

  • 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

    • _internalSetCommandContext

      public void _internalSetCommandContext(Optional<CommandContext> 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. 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 ValueEntity.Effect.Builder<S> effects()