Package org.a2aproject.sdk.server.tasks

Interface PushNotificationConfigStore

All Known Implementing Classes:
InMemoryPushNotificationConfigStore, JpaDatabasePushNotificationConfigStore
public interface PushNotificationConfigStore
Interface for storing and retrieving push notification configurations for tasks.

Push notification configurations specify where and how to deliver task state updates to external systems (webhook URLs, authentication headers, etc.). A task can have multiple push notification configurations for different endpoints or use cases.

Configuration ID Semantics

Each push notification config has an ID:
  • If not provided in TaskPushNotificationConfig, defaults to the task ID
  • Multiple configs per task require unique IDs (e.g., "webhook-1", "webhook-2")
  • Used for retrieval and deletion of specific configurations

Pagination Support

getInfo(ListTaskPushNotificationConfigsParams) supports pagination for tasks with many push notification configurations:
  • pageSize: Maximum number of configs to return (0 = unlimited)
  • pageToken: Continuation token from previous response
  • Returns ListTaskPushNotificationConfigsResult with configs and next page token

Default Implementation

InMemoryPushNotificationConfigStore:
  • Stores configs in ConcurrentHashMap
  • Thread-safe for concurrent operations
  • Configs lost on application restart

Alternative Implementations

  • extras/push-notification-config-store-database-jpa: Database persistence with JPA
Database implementations survive restarts and enable config sharing across server instances.

CDI Extension Pattern


 @ApplicationScoped
 @Alternative
 @Priority(50)
 public class JpaDatabasePushNotificationConfigStore implements PushNotificationConfigStore {
     @PersistenceContext
     EntityManager em;

     @Transactional
     public TaskPushNotificationConfig setInfo(TaskPushNotificationConfig config) {
         // JPA persistence logic
     }
 }

Thread Safety

Implementations must be thread-safe. Multiple threads may call methods concurrently for the same or different tasks.
See Also:

  • Method Details

    • setInfo

      TaskPushNotificationConfig setInfo(TaskPushNotificationConfig notificationConfig)
      Sets or updates the push notification configuration for a task.

      If notificationConfig.id() is null or empty, it's set to the task ID. If a config with the same ID already exists for this task, it's replaced.

      Parameters:
      notificationConfig - the task push notification configuration
      Returns:
      the potentially updated configuration (with ID set if it was null)

    • setInfo

      default TaskPushNotificationConfig setInfo(TaskPushNotificationConfig notificationConfig, @Nullable String protocolVersion)
      Sets or updates the push notification configuration for a task, along with the protocol version that registered it.

      This merged method ensures the protocol version is stored using the normalized config ID (after setInfo(TaskPushNotificationConfig) applies defaults).

      Parameters:
      notificationConfig - the task push notification configuration
      protocolVersion - the protocol version string, or null to use AgentInterface.CURRENT_PROTOCOL_VERSION
      Returns:
      the potentially updated configuration (with ID set if it was null)

    • resolveProtocolVersion

      static String resolveProtocolVersion(@Nullable String protocolVersion)
      Resolves the protocol version, defaulting null to the current protocol version.

    • getInfo

      ListTaskPushNotificationConfigsResult getInfo(ListTaskPushNotificationConfigsParams params)
      Retrieves push notification configurations for a task with pagination support.

      Returns all configs if params.pageSize() is 0. Otherwise, returns up to pageSize configs and a continuation token for the next page.

      Pagination Example: 

      
 // First page
 ListTaskPushNotificationConfigsParams params =
     new ListTaskPushNotificationConfigsParams(taskId, 10, null, tenant);
 ListTaskPushNotificationConfigsResult result = store.getInfo(params);

 // Next page
 if (result.nextPageToken() != null) {
     params = new ListTaskPushNotificationConfigsParams(
         taskId, 10, result.nextPageToken(), tenant);
     result = store.getInfo(params);
 }
      Parameters:
      params - the query parameters including task ID, page size, and page token
      Returns:
      the configurations for this task (empty list if none found)

    • deleteInfo

      void deleteInfo(String taskId, String configId)
      Deletes a push notification configuration for a task.

      If configId is null, it defaults to the task ID (deletes the default config). If no config exists with the given ID, this method returns normally (idempotent).

      Parameters:
      taskId - the task ID
      configId - the push notification configuration ID (null = use task ID)

    • getProtocolVersion

      default String getProtocolVersion(String taskId, String configId)
      Gets the protocol version associated with a push notification configuration.
      Parameters:
      taskId - the task ID
      configId - the push notification configuration ID
      Returns:
      the protocol version string, defaults to the current protocol version if not set

    • getProtocolVersions

      default Map<String,String> getProtocolVersions(String taskId)
      Gets all protocol versions for a task's push notification configurations in a single call.
      Parameters:
      taskId - the task ID
      Returns:
      a map of config ID to protocol version (only includes configs with a version set)