Package org.a2aproject.sdk.server.tasks

Interface TaskStateProvider

All Known Implementing Classes:
InMemoryTaskStore, JpaDatabaseTaskStore
public interface TaskStateProvider
Provider interface for determining the active state of a task.

This interface decouples the queue lifecycle management from the task state persistence layer. Implementations should check the authoritative task state to determine whether a task is considered "active" for queue management purposes.

A task is typically considered active if:

  • Its state is not final (e.g., not COMPLETED, CANCELED, FAILED, etc.), OR
  • Its state is final but it was finalized recently (within a configurable grace period)

The grace period mechanism handles race conditions in both replicated and non-replicated environments where events may be in-flight when a task finalizes.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    isTaskActive(String taskId)
    Determines whether a task is considered active for queue management purposes.
    boolean
    isTaskFinalized(String taskId)
    Determines whether a task is in a final state, ignoring the grace period.

  • Method Details

    • isTaskActive

      boolean isTaskActive(String taskId)
      Determines whether a task is considered active for queue management purposes.

      This method includes the grace period in its check. A task is considered active if:

      • Its state is not final, OR
      • Its state is final but finalized within the grace period (now < finalizedAt + gracePeriod)

      This method is used to decide whether to process late-arriving events.

      Parameters:
      taskId - the ID of the task to check
      Returns:
      true if the task is active (or recently finalized within grace period), false otherwise

    • isTaskFinalized

      boolean isTaskFinalized(String taskId)
      Determines whether a task is in a final state, ignoring the grace period.

      This method performs an immediate check: returns true only if the task is in a final state (COMPLETED, CANCELED, FAILED, etc.), regardless of when it was finalized.

      This method is used by cleanup callbacks and MainQueue closing logic to decide whether a queue can be closed and removed. By ignoring the grace period, it ensures responsive cleanup while late in-flight events are still handled by the grace period mechanism for isTaskActive.

      Parameters:
      taskId - the ID of the task to check
      Returns:
      true if the task is in a final state (ignoring grace period), false otherwise