# 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 returned completable future, if completed successfully, completes
+ * with an {@link HttpResponse}{@code {@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:
* 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 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 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
*
*
* @param