Package org.a2aproject.sdk.server.tasks

Class BasePushNotificationSender

java.lang.Object
org.a2aproject.sdk.server.tasks.BasePushNotificationSender
All Implemented Interfaces:
PushNotificationSender
@ApplicationScoped public class BasePushNotificationSender extends Object implements PushNotificationSender

  • Field Details

    • DEFAULT_PAGE_SIZE

      public static final int DEFAULT_PAGE_SIZE
      See Also:

    • DISPATCH_EXECUTOR_NAME

      public static final String DISPATCH_EXECUTOR_NAME
      CDI @Named qualifier ("a2a.pushNotificationDispatch") for an optional application-provided Executor used to dispatch push notifications asynchronously.

      Applications can produce a bean with this name to supply a custom thread pool (e.g. for sizing or monitoring). When an instrumentation module (such as the OpenTelemetry server extra) is present, it produces an @Instrumented Executor that wraps the application's @Named executor (or a default pool) with context propagation.

      Resolution order (see the CDI constructor):

      1. @Instrumented Executor (instrumented wrapper)
      2. @Named("a2a.pushNotificationDispatch") Executor (application-provided)
      3. ForkJoinPool.commonPool() as last resort
      See Also:

  • Constructor Details

    • BasePushNotificationSender

      protected BasePushNotificationSender()
      No-args constructor for CDI proxy creation. CDI requires a non-private constructor to create proxies for @ApplicationScoped beans. All fields are initialized by the @Inject constructor during actual bean creation.

    • BasePushNotificationSender

      public BasePushNotificationSender(PushNotificationConfigStore configStore, PushNotificationUrlValidator urlValidator)

    • BasePushNotificationSender

      @Inject public BasePushNotificationSender(PushNotificationConfigStore configStore, jakarta.enterprise.inject.Instance<PushNotificationPayloadFormatter> formatters, PushNotificationUrlValidator urlValidator, jakarta.enterprise.inject.Instance<A2AHttpClient> httpClient, jakarta.enterprise.inject.Instance<A2AHttpClient> propagatingClient, jakarta.enterprise.inject.Instance<Executor> instrumentedExecutor, @Named("a2a.pushNotificationDispatch") jakarta.enterprise.inject.Instance<Executor> dispatchExecutor)
      CDI injection constructor.

      The HTTP client is resolved in order of preference:

      1. A @Instrumented bean (e.g. one produced by the OpenTelemetry server extra, which wraps the application's client with trace-context injection)
      2. An unqualified A2AHttpClient bean provided by the application (custom mTLS, proxy, authentication, etc.)
      3. A2AHttpClientFactory.create(A2AHttpClientConfiguration) as last resort

      The dispatch executor is resolved in order of preference:

      1. An @Instrumented Executor (e.g. one produced by the OpenTelemetry server extra, which wraps the application's executor with context propagation)
      2. A @Named("a2a.pushNotificationDispatch") Executor provided by the application
      3. ForkJoinPool.commonPool() as last resort
      Parameters:
      configStore - the store for push notification configurations
      formatters - optional formatters for protocol-version-specific payloads
      urlValidator - validates push notification URLs to prevent SSRF
      httpClient - optional CDI-provided HTTP client
      propagatingClient - optional context-propagating HTTP client that wraps the application's client with observability instrumentation
      instrumentedExecutor - optional instrumented executor with context propagation
      dispatchExecutor - optional named executor for async dispatch

    • BasePushNotificationSender

      public BasePushNotificationSender(PushNotificationConfigStore configStore, A2AHttpClient httpClient, PushNotificationUrlValidator urlValidator)

    • BasePushNotificationSender

      public BasePushNotificationSender(PushNotificationConfigStore configStore, A2AHttpClient httpClient, List<PushNotificationPayloadFormatter> formatters, PushNotificationUrlValidator urlValidator)

  • Method Details

    • sendNotification

      public boolean sendNotification(StreamingEventKind event, @Nullable Task taskSnapshot)
      Description copied from interface: PushNotificationSender
      Sends a push notification containing a streaming event.

      Called after the event has been persisted to TaskStore. The payload format depends on the protocol version used to register the push notification configuration.

      • v1.0 (default): The event is wrapped in a StreamResponse format (per A2A spec section 4.3.3) with the appropriate oneof field set (task, message, statusUpdate, or artifactUpdate).
      • v0.3: The payload is a v0.3 Task JSON object, using the provided taskSnapshot. Message events are skipped.

      Retrieve push notification URLs or messaging configurations from PushNotificationConfigStore using the task ID extracted from the event.

      Supported event types:

      Error Handling: Return false on delivery failures (network errors, HTTP errors). Throwing is reserved for precondition violations such as a missing task ID or an unsupported event type — these signal caller bugs. Callers catch all exceptions so neither case fails the client request.

      Specified by:
      sendNotification in interface PushNotificationSender
      Parameters:
      event - the streaming event to send.
      taskSnapshot - the current state of the task after the event has been applied. Used by formatters for older protocol versions that require the full task state in notifications.
      Returns:
      true if all notifications were delivered successfully, false if one or more deliveries failed

    • extractTaskId

      protected @Nullable String extractTaskId(StreamingEventKind event)
      Extracts the task ID from a streaming event.
      Parameters:
      event - the streaming event
      Returns:
      the task ID, or null if the event type does not carry one (e.g. a Message without a task ID)
      Throws:
      IllegalStateException - if the event is not a recognized StreamingEventKind subtype