# HG changeset patch # User chegar # Date 1516305077 0 # Node ID 1f88e15870671376b7b4f273af5ac2758e3bc127 # Parent de352132c7e89e7ab3b01041ead1cdd69021f71f http-cient-branch: cleanup push promise spec diff -r de352132c7e8 -r 1f88e1587067 src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java --- a/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java Thu Jan 18 16:52:14 2018 +0000 +++ b/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpClient.java Thu Jan 18 19:51:17 2018 +0000 @@ -432,6 +432,29 @@ * Sends the given request asynchronously using this client and the given * response handler. * + *

Equivalent to {@code sendAsync(request, responseBodyHandler, null)}. + * + * @param the response body type + * @param request the request + * @param responseBodyHandler the response body handler + * @return a {@code CompletableFuture>} + */ + public abstract CompletableFuture> + sendAsync(HttpRequest request, + BodyHandler responseBodyHandler); + + /** + * Sends the given request asynchronously using this client with the given + * response body handler and push promise handler. + * + *

The returned completable future, if completed successfully, completes + * with an {@link HttpResponse}{@code } that contains the response status, + * headers, and body ( as handled by given response body handler ). + * + *

{@linkplain PushPromiseHandler Push promises} received, if any, are + * handled by the given {@code pushPromiseHandler}. A {@code null} valued + * {@code pushPromiseHandler} rejects any push promises. + * *

The returned completable future completes exceptionally with: *

* * @param the response body type - * @param req the request - * @param responseBodyHandler the response body handler - * @return a {@code CompletableFuture>} - */ - public abstract CompletableFuture> - sendAsync(HttpRequest req, - BodyHandler responseBodyHandler); - - /** - * Sends the given request asynchronously using this client with the given - * response body handler and push promise handler. - * - * @param the response body type - * @param req the request + * @param request the request * @param responseBodyHandler the response body handler * @param pushPromiseHandler push promise handler, may be null * @return a {@code CompletableFuture>} */ public abstract CompletableFuture> - sendAsync(HttpRequest req, + sendAsync(HttpRequest request, BodyHandler responseBodyHandler, PushPromiseHandler pushPromiseHandler); diff -r de352132c7e8 -r 1f88e1587067 src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java --- a/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java Thu Jan 18 16:52:14 2018 +0000 +++ b/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java Thu Jan 18 19:51:17 2018 +0000 @@ -725,17 +725,49 @@ } /** - * A handler of push promises ... + * A handler for push promises. + * + *

A push promise is a synthetic request sent by an HTTP/2 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. + * + *

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. + * + * @param the push promise response body type */ public interface PushPromiseHandler { /** - * Notifies of an incoming Push Promise. The enclosing request from the user and the push promise - * are supplied as parameters, and also a {@link Function} which must be called in the implementation - * of this method, if the server push is to be accepted. If this method returns without the function - * being called, then the push will be cancelled. + * 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 {@code acceptor} + * function. The {@code acceptor} function must be passed a non-null + * {@code BodyHandler}, that is to be used to handle the promise's + * response body. The acceptor function will return a {@code + * CompletableFuture} that completes with the promise's response. + * + *

If the {@code acceptor} function is not successfully invoked, + * then the push promise is rejected. The {@code acceptor} function will + * throw an {@code IllegalStateException} if invoked more than once. + * + * @param initiatingRequest the initiating client-send request + * @param pushPromiseRequest the synthetic push request + * @param acceptor the acceptor function that must be successfully + * invoked to accept the push promise */ public void applyPushPromise( - HttpRequest initial, HttpRequest pushPromise, + HttpRequest initiatingRequest, + HttpRequest pushPromiseRequest, Function,CompletableFuture>> acceptor ); @@ -755,7 +787,7 @@ @Override public void applyPushPromise( HttpRequest initiatingRequest, HttpRequest pushRequest, - Function,CompletableFuture>> acceptor) + Function,CompletableFuture>> acceptor) { URI initiatingURI = initiatingRequest.uri(); URI pushRequestURI = pushRequest.uri(); @@ -779,7 +811,8 @@ if (initiatingPort != pushPort) return; - CompletableFuture> cf = acceptor.apply(pushPromiseHandler.apply(pushRequest)); + CompletableFuture> cf = + acceptor.apply(pushPromiseHandler.apply(pushRequest)); pushPromisesMap.put(pushRequest, cf); } } @@ -788,14 +821,14 @@ * 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 synthetic push - * request ( 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 {@linplain HttpRequest#equal - * 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 for each push promise accepted. + * The entry's key is the push request, and the entry's value is a + * {@code 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 + * {@linkplain HttpRequest#equals 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, @@ -803,16 +836,18 @@ * been issued by the server and avoid making, possibly, unnecessary * requests. * - *

The delivery of pushed content is not synchronized with the - * delivery of the main response. However, when the main response - * has been fully received, the map is guaranteed to be fully populated - * with no more entries added. The individual {@code CompletableFutures} - * contained in the Map may or may not already be completed at this point. + *

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 + * {@code CompletableFutures} contained in the map may or may not + * already be completed at this point. * - * @param the push promise body type + * @param the push promise response body type * @param pushPromiseHandler t he body handler to use for push promises * @param pushPromisesMap a map to accumulate push promises into - * @return a push promise body handler + * @return a push promise handler */ public static PushPromiseHandler withPushPromises(Function> pushPromiseHandler,