Package akka.javasdk.agent.task

Class TaskEntity

Object
akka.javasdk.eventsourcedentity.EventSourcedEntity<TaskState,TaskEvent>
akka.javasdk.agent.task.TaskEntity
@Component(id="akka-task") public final class TaskEntity extends EventSourcedEntity<TaskState,TaskEvent>
The built-in Event Sourced Entity that stores each task's state and lifecycle history.

The Akka runtime registers this entity automatically when a service uses tasks. Application code normally drives tasks through TaskClient (via componentClient.forTask(taskId)) rather than by calling this entity directly. Like any entity, its events can be consumed with a subscribing Consumer, for example to react to task completions.

Command validity is governed by the task's TaskStatus: for example a task can only be assigned when PENDING, and completion is idempotent once the task is in a terminal state.

  • Constructor Details

  • Method Details

    • emptyState

      public TaskState emptyState()
      Description copied from class: EventSourcedEntity
      Returns the initial empty state object for this entity. This state is used when the entity is first created and before any events have been persisted and applied.

      Also known as "zero state" or "neutral state". This method is called when the entity is instantiated for the first time or when recovering from the journal without any persisted events.

      The default implementation returns null. Override this method to provide a more meaningful initial state for your entity.

      Overrides:
      emptyState in class EventSourcedEntity<TaskState,TaskEvent>
      Returns:
      the initial state object, or null if no initial state is needed

    • create

      public EventSourcedEntity.Effect<akka.Done> create(TaskEntity.CreateRequest request)
      Create the task. Fails if a task with this ID already exists.

    • assign

      public EventSourcedEntity.Effect<akka.Done> assign(String assignee)
      Assign the task to an owner. Only valid when PENDING and not already assigned.

    • start

      public EventSourcedEntity.Effect<akka.Done> start()
      Mark the task as in progress. Only valid when ASSIGNED.

    • complete

      public EventSourcedEntity.Effect<akka.Done> complete(String result)
      Complete the task with a serialized result and publish a TaskNotification.Completed. Idempotent once the task is in any terminal state.

    • rejectResult

      public EventSourcedEntity.Effect<akka.Done> rejectResult(TaskEntity.RejectResultRequest request)
      Record that a TaskRule rejected the completion result and publish a TaskNotification.ResultRejected. The task moves to RESULT_REJECTED so the assignee can correct and resubmit.

    • fail

      public EventSourcedEntity.Effect<akka.Done> fail(String reason)
      Fail the task and publish a TaskNotification.Failed. Idempotent once the task is in any terminal state.

    • cancel

      public EventSourcedEntity.Effect<akka.Done> cancel(String reason)
      Cancel the task before execution begins and publish a TaskNotification.Cancelled. Only valid when PENDING or ASSIGNED; idempotent once the task is in any terminal state.

    • reassign

      public EventSourcedEntity.Effect<akka.Done> reassign(TaskEntity.ReassignRequest request)
      Reassign the task to a new owner. Only valid when IN_PROGRESS.

    • notifications

      public NotificationPublisher.NotificationStream<TaskNotification> notifications()
      The stream of TaskNotifications published by this task.

    • getState

      public EventSourcedEntity.ReadOnlyEffect<TaskState> getState()
      The task's current state. Fails if the task does not exist.

    • applyEvent

      public TaskState applyEvent(TaskEvent event)
      Description copied from class: EventSourcedEntity
      This is the main event handler method. Whenever an event is persisted, this handler will be called. It should return the new state of the entity.

      Note that this method is called in two situations:

      • when one or more events are persisted by the command handler, this method is called to produce the new state of the entity.
      • when instantiating an entity from the event journal, this method is called to restore the state of the entity.
      It's important to keep the event handler side effect free. This means that it should only apply the event on the current state and return the updated state. This is because the event handler is called during recovery.

      Events are required to inherit from a common sealed interface, and it's recommend to implement this method using a switch statement. As such, the compiler can check if all existing events are being handled. 

      
 // example of sealed event interface with concrete events implementing it
 public sealed interface Event {
   @TypeName("created")
   public record UserCreated(String name, String email) implements Event {};
   @TypeName("email-updated")
   public record EmailUpdated(String newEmail) implements Event {};
 }

 // example of applyEvent implementation
 public User applyEvent(Event event) {
    return switch (event) {
      case UserCreated userCreated -> new User(userCreated.name, userCreated.email);
      case EmailUpdated emailUpdated -> this.copy(email = emailUpdated.newEmail);
    }
 }
      Specified by:
      applyEvent in class EventSourcedEntity<TaskState,TaskEvent>