Package akka.javasdk.keyvalueentity

Interface KeyValueEntity.Effect.Builder<S>

Type Parameters:
S - The type of the state for this entity
Enclosing interface:
KeyValueEntity.Effect<T>
public static interface KeyValueEntity.Effect.Builder<S>
Builder for constructing effects that describe the actions to be performed after command processing. Use this to create effects that update state, reply to callers, or handle errors.

  • Method Details

    • updateState

      KeyValueEntity.Effect.OnSuccessBuilder<S> updateState(S newState)
      Updates the entity state with the provided new state. The new state will replace the current state entirely.
      Parameters:
      newState - the new state to persist, replacing the current state
      Returns:
      a builder for chaining additional effects like replies

    • updateStateWithMetadata

      KeyValueEntity.Effect.OnSuccessBuilder<S> updateStateWithMetadata(S newState, Metadata metadata)
      Updates the entity state with the provided new state and additional metadata together with the state. The new state will replace the current state entirely.
      Parameters:
      newState - the new state to persist, replacing the current state
      Returns:
      a builder for chaining additional effects like replies

    • updateReplicationFilter

      KeyValueEntity.Effect.OnSuccessBuilder<S> updateReplicationFilter(ReplicationFilter.Builder filter)
      Change the replication filter for this entity updating the state.

      State is by default replicated to all regions that have been enabled for the service. This method allows you to control which regions participate in the replication for this specific entity instance. This is useful for regulatory reasons or as cost optimization.

      The replication filter can only be updated from the primary region of the entity, or the entity will become the primary if using the request-region primary selection strategy. The filter is durable for the specific entity instance and can be changed without deploying a new version.

      The region where the update is made (the self region) is automatically included in the replication filter. The changes are additive, meaning that if you first update the filter to include one region and then later make another update to include a different region from the same entity, both regions are included.

      Parameters:
      filter - the replication filter defining which regions to include or exclude
      Returns:
      an effect builder for chaining additional operations

    • deleteEntity

      KeyValueEntity.Effect.OnSuccessBuilder<S> deleteEntity()
      Marks the entity for deletion. After deletion, the entity will still exist with an empty state for some time before being completely removed. No additional state updates are allowed after deletion.
      Returns:
      a builder for chaining additional effects like replies

    • reply

      <T> KeyValueEntity.ReadOnlyEffect<T> reply(T message)
      Creates a reply message to send back to the caller without updating the entity state. Use this for read-only operations or when the command doesn't require state changes.
      Type Parameters:
      T - the type of the reply message
      Parameters:
      message - the payload of the reply message
      Returns:
      a read-only effect containing the reply

    • reply

      <T> KeyValueEntity.ReadOnlyEffect<T> reply(T message, Metadata metadata)
      Creates a reply message with additional metadata to send back to the caller without updating the entity state.
      Type Parameters:
      T - the type of the reply message
      Parameters:
      message - the payload of the reply message
      metadata - additional metadata to include with the reply
      Returns:
      a read-only effect containing the reply

    • error

      <T> KeyValueEntity.ReadOnlyEffect<T> error(String message)
      Creates an error reply to reject the command and inform the caller of the failure. The entity state will not be modified when returning an error.
      Type Parameters:
      T - the type of the expected reply message
      Parameters:
      message - the error message.
      Returns:
      a read-only effect containing the error

    • error

      <T> KeyValueEntity.ReadOnlyEffect<T> error(CommandException commandException)
      Create an error reply. CommandException will be serialized and sent to the client. It's possible to catch it with try-catch statement or CompletionStage API when using async ComponentClient API.
      Type Parameters:
      T - The type of the message that must be returned by this call.
      Parameters:
      commandException - The command exception to be returned.
      Returns:
      An error reply.