Package akka.javasdk.impl.agent.task

Class BacklogEntity

Object
akka.javasdk.eventsourcedentity.EventSourcedEntity<BacklogState,BacklogEvent>
akka.javasdk.impl.agent.task.BacklogEntity
@InternalApi @Component(id="akka-backlog") public final class BacklogEntity extends EventSourcedEntity<BacklogState,BacklogEvent>
INTERNAL API Manages a shared backlog of task references with atomic claiming semantics. Multiple agents can browse, claim, release, and transfer tasks concurrently.

  • Constructor Details

  • Method Details

    • emptyState

      public BacklogState 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<BacklogState,BacklogEvent>
      Returns:
      the initial state object, or null if no initial state is needed

    • create

      public EventSourcedEntity.Effect<akka.Done> create(String name)
      Create this backlog with a name.

    • addTask

      public EventSourcedEntity.Effect<akka.Done> addTask(String taskId)
      Add a task reference to this backlog. The task must already exist in TaskEntity.

    • claim

      public EventSourcedEntity.Effect<akka.Done> claim(BacklogEntity.ClaimRequest request)
      Atomic first-come-first-served claim.

    • release

      public EventSourcedEntity.Effect<akka.Done> release(String taskId)
      Release a claimed task back to unclaimed.

    • transfer

      public EventSourcedEntity.Effect<akka.Done> transfer(BacklogEntity.TransferRequest request)
      Transfer a claimed task directly to a different agent.

    • cancelUnclaimed

      public EventSourcedEntity.Effect<akka.Done> cancelUnclaimed()
      Remove all unclaimed tasks from the backlog.

    • close

      public EventSourcedEntity.Effect<akka.Done> close()
      Close the backlog — no further modifications allowed.

    • getState

      public EventSourcedEntity.ReadOnlyEffect<BacklogState> getState()
      Get the current state of the backlog.

    • notifications

      public NotificationPublisher.NotificationStream<BacklogNotification> notifications()

    • applyEvent

      public BacklogState applyEvent(BacklogEvent 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<BacklogState,BacklogEvent>