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:

• KeyValueEntityContext
• Custom types provided by a DependencyProvider from the service setup

Concrete class must be annotated with ComponentId.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	KeyValueEntity.Effect<T>	An Effect is a description of what the runtime needs to do after the command is handled.
static interface	KeyValueEntity.ReadOnlyEffect<T>	An effect that is known to be read only and does not update the state of the entity.

Constructor Summary

Constructors

Constructor	Description
KeyValueEntity()

Method Summary

Modifier and Type	Method	Description
protected final CommandContext	commandContext()	Additional context and metadata for a command handler.
protected final S	currentState()	Returns the state as currently stored.
protected final KeyValueEntity.Effect.Builder<S>	effects()
S	emptyState()	Implement by returning the initial empty state object.
protected boolean	isDeleted()	Returns true if the entity has been deleted.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

isDeleted

protected boolean isDeleted()

Returns true if the entity has been deleted.

effects

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