Interface HttpResponse.PushPromiseHandler<T>

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.

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.

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.

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.