HttpResponse.PushPromiseHandler (Java SE 26 & JDK 26)
Description: declaration: module: java.net.http, package: java.net.http, interface: HttpResponse, interface: PushPromiseHandler
Keywords: java.net.http.HttpResponse.PushPromiseHandler interface

# Interface HttpResponse.PushPromiseHandler<T>

Type Parameters:
  `T` - the push promise response body type

Enclosing interface:
  `HttpResponse<T>`

public static interface HttpResponse.PushPromiseHandler<T>
A handler for push promises.

A push promise is a synthetic request sent by an HTTP/2 or HTTP/3 server when retrieving an initiating client-sent request. The server has determined, possibly through inspection of the initiating request, that the client will likely need the promised resource, and hence pushes a synthetic push request, in the form of a push promise, to the client. The client can choose to accept or reject the push promise request.

For HTTP/2, a push promise request may be received up to the point where the response body of the initiating client-sent request has been fully received. The delivery of a push promise response, however, is not coordinated with the delivery of the response to the initiating client-sent request. These are delivered with the `applyPushPromise(HttpRequest, HttpRequest, Function)` method.

For HTTP/3, push promises are handled in a similar way, except that promises of the same resource (request URI, request headers and response body) can be promised multiple times, but are only delivered by the server (and this API) once though the method `applyPushPromise(HttpRequest, HttpRequest, PushId, Function)`. Subsequent promises of the same resource, receive a notification only of the promise by the method `notifyAdditionalPromise(HttpRequest, PushId)`. The same `HttpResponse.PushPromiseHandler.PushId` is supplied for each of these notifications. Additionally, HTTP/3 push promises are not restricted to a context of a single initiating request. The same push promise can be delivered and then notified across multiple client initiated requests within the same HTTP/3 (QUIC) connection.

Since:
  11

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Interface
  Description
  `static interface`
  `HttpResponse.PushPromiseHandler.PushId`
  Represents a HTTP/3 PushID.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default void`
  `applyPushPromise(HttpRequest initiatingRequest, HttpRequest pushPromiseRequest, HttpResponse.PushPromiseHandler.PushId pushid, Function<HttpResponse.BodyHandler<T>, CompletableFuture<HttpResponse<T>>> acceptor)`
  Notification of the first occurrence of an HTTP/3 incoming push promise.
  `void`
  `applyPushPromise(HttpRequest initiatingRequest, HttpRequest pushPromiseRequest, Function<HttpResponse.BodyHandler<T>, CompletableFuture<HttpResponse<T>>> acceptor)`
  Notification of an incoming push promise.
  `default void`
  `notifyAdditionalPromise(HttpRequest initiatingRequest, HttpResponse.PushPromiseHandler.PushId pushid)`
  Invoked for each additional HTTP/3 Push Promise.
  `static <T> HttpResponse.PushPromiseHandler<T>`
  `of(Function<HttpRequest, HttpResponse.BodyHandler<T>> pushPromiseHandler, ConcurrentMap<HttpRequest, CompletableFuture<HttpResponse<T>>> pushPromisesMap)`
  Returns a push promise handler that accumulates push promises, and their responses, into the given map.

- ## Method Details

  - ### applyPushPromise

    void applyPushPromise(HttpRequest initiatingRequest, HttpRequest pushPromiseRequest, Function<HttpResponse.BodyHandler<T>, CompletableFuture<HttpResponse<T>>> acceptor)
    Notification of an incoming push promise.

    This method is invoked once for each push promise received, up to the point where the response body of the initiating client-sent request has been fully received.

    A push promise is accepted by invoking the given `acceptor` function. The `acceptor` function must be passed a non-null `BodyHandler`, that is to be used to handle the promise's response body. The acceptor function will return a `CompletableFuture` that completes with the promise's response.

    If the `acceptor` function is not successfully invoked, then the push promise is rejected. The `acceptor` function will throw an `IllegalStateException` if invoked more than once.

    This method is invoked for all HTTP/2 push promises and also by default for the first promise of all HTTP/3 push promises. If `applyPushPromise(HttpRequest, HttpRequest, PushId, Function)` is overridden, then this method is not directly invoked for HTTP/3 push promises.

    Parameters:
      `initiatingRequest` - the initiating client-send request
      `pushPromiseRequest` - the synthetic push request
      `acceptor` - the acceptor function that must be successfully invoked to accept the push promise

  - ### applyPushPromise

    default void applyPushPromise(HttpRequest initiatingRequest, HttpRequest pushPromiseRequest, HttpResponse.PushPromiseHandler.PushId pushid, Function<HttpResponse.BodyHandler<T>, CompletableFuture<HttpResponse<T>>> acceptor)
    Notification of the first occurrence of an HTTP/3 incoming push promise. Subsequent promises of the same resource (with the same PushId) are notified using `notifyAdditionalPromise(HttpRequest, PushId)`.

    This method is invoked once for each push promise received, up to the point where the response body of the initiating client-sent request has been fully received.

    A push promise is accepted by invoking the given `acceptor` function. The `acceptor` function must be passed a non-null `BodyHandler`, that is to be used to handle the promise's response body. The acceptor function will return a `CompletableFuture` that completes with the promise's response.

    If the `acceptor` function is not successfully invoked, then the push promise is rejected. The `acceptor` function will throw an `IllegalStateException` if invoked more than once.

    Implementation Requirements:
      the default implementation invokes `applyPushPromise(HttpRequest, HttpRequest, Function)`. This allows `PushPromiseHandlers` from previous releases to handle HTTP/3 push promise in a reasonable way.
    Parameters:
      `initiatingRequest` - the client request that resulted in the promise
      `pushPromiseRequest` - the promised HttpRequest from the server
      `pushid` - the PushId which can be linked to subsequent notifications
      `acceptor` - the acceptor function that must be successfully invoked to accept the push promise
    Since:
      26

  - ### notifyAdditionalPromise

    default void notifyAdditionalPromise(HttpRequest initiatingRequest, HttpResponse.PushPromiseHandler.PushId pushid)
    Invoked for each additional HTTP/3 Push Promise. The `pushid` links the promise to the original promised `HttpRequest` and `HttpResponse`. Additional promises generally result from different client initiated requests.
    Implementation Requirements:
      The default implementation of this method does nothing.
    Parameters:
      `initiatingRequest` - the client initiated request which resulted in the push
      `pushid` - the pushid which may have been notified previously
    Since:
      26

  - ### of

    static <T> HttpResponse.PushPromiseHandler<T> of(Function<HttpRequest, HttpResponse.BodyHandler<T>> pushPromiseHandler, ConcurrentMap<HttpRequest, CompletableFuture<HttpResponse<T>>> pushPromisesMap)
    Returns a push promise handler that accumulates push promises, and their responses, into the given map.

    Entries are added to the given map for each push promise accepted. The entry's key is the push request, and the entry's value is a `CompletableFuture` that completes with the response corresponding to the key's push request. A push request is rejected / cancelled if there is already an entry in the map whose key is equal to it. A push request is rejected / cancelled if it does not have the same origin as its initiating request.

    Entries are added to the given map as soon as practically possible when a push promise is received and accepted. That way code, using such a map like a cache, can determine if a push promise has been issued by the server and avoid making, possibly, unnecessary requests.

    The delivery of a push promise response is not coordinated with the delivery of the response to the initiating client-sent request. However, when the response body for the initiating client-sent request has been fully received, the map is guaranteed to be fully populated, that is, no more entries will be added. The individual `CompletableFutures` contained in the map may or may not already be completed at this point.

    Type Parameters:
      `T` - the push promise response body type
    Parameters:
      `pushPromiseHandler` - the body handler to use for push promises
      `pushPromisesMap` - a map to accumulate push promises into
    Returns:
      a push promise handler