--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java Tue Sep 12 19:03:39 2017 +0200
@@ -0,0 +1,731 @@
+/*
+ * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation. Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+package jdk.incubator.http;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.net.URI;
+import jdk.incubator.http.ResponseProcessors.MultiFile;
+import jdk.incubator.http.ResponseProcessors.MultiProcessorImpl;
+import static jdk.incubator.http.internal.common.Utils.unchecked;
+import static jdk.incubator.http.internal.common.Utils.charsetFrom;
+import java.nio.ByteBuffer;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.OpenOption;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.StandardOpenOption;
+import java.util.Map;
+import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+import java.util.concurrent.Flow;
+import java.util.function.Consumer;
+import java.util.function.Function;
+import javax.net.ssl.SSLParameters;
+
+/**
+ * Represents a response to a {@link HttpRequest}.
+ * {@Incubating}
+ *
+ * <p>A {@code HttpResponse} is available when the response status code and
+ * headers have been received, and typically after the response body has also
+ * been received. This depends on the response body handler provided when
+ * sending the request. In all cases, the response body handler is invoked
+ * before the body is read. This gives applications an opportunity to decide
+ * how to handle the body.
+ *
+ * <p> Methods are provided in this class for accessing the response headers,
+ * and response body.
+ * <p>
+ * <b>Response handlers and processors</b>
+ * <p>
+ * Response bodies are handled at two levels. Application code supplies a response
+ * handler ({@link BodyHandler}) which may examine the response status code
+ * and headers, and which then returns a {@link BodyProcessor} to actually read
+ * (or discard) the body and convert it into some useful Java object type. The handler
+ * can return one of the pre-defined processor types, or a custom processor, or
+ * if the body is to be discarded, it can call {@link BodyProcessor#discard(Object)
+ * BodyProcessor.discard()} and return a processor which discards the response body.
+ * Static implementations of both handlers and processors are provided in
+ * {@link BodyHandler BodyHandler} and {@link BodyProcessor BodyProcessor} respectively.
+ * In all cases, the handler functions provided are convenience implementations
+ * which ignore the supplied status code and
+ * headers and return the relevant pre-defined {@code BodyProcessor}.
+ * <p>
+ * See {@link BodyHandler} for example usage.
+ *
+ * @param <T> the response body type
+ * @since 9
+ */
+public abstract class HttpResponse<T> {
+
+ /**
+ * Creates an HttpResponse.
+ */
+ protected HttpResponse() { }
+
+ /**
+ * Returns the status code for this response.
+ *
+ * @return the response code
+ */
+ public abstract int statusCode();
+
+ /**
+ * Returns the initial {@link HttpRequest} that initiated the exchange.
+ *
+ * @return the request
+ */
+ public abstract HttpRequest request();
+
+ /**
+ * Returns the final {@link HttpRequest} that was sent on the wire for the
+ * exchange ( may, or may not, be the same as the initial request ).
+ *
+ * @return the request
+ */
+ public abstract HttpRequest finalRequest();
+
+ /**
+ * Returns the received response headers.
+ *
+ * @return the response headers
+ */
+ public abstract HttpHeaders headers();
+
+ /**
+ * Returns the received response trailers, if there are any, when they
+ * become available. For many response processor types this will be at the same
+ * time as the {@code HttpResponse} itself is available. In such cases, the
+ * returned {@code CompletableFuture} will be already completed.
+ *
+ * @return a CompletableFuture of the response trailers (may be empty)
+ */
+ public abstract CompletableFuture<HttpHeaders> trailers();
+
+ /**
+ * Returns the body. Depending on the type of {@code T}, the returned body may
+ * represent the body after it was read (such as {@code byte[]}, or
+ * {@code String}, or {@code Path}) or it may represent an object with
+ * which the body is read, such as an {@link java.io.InputStream}.
+ *
+ * @return the body
+ */
+ public abstract T body();
+
+ /**
+ * Returns the {@link javax.net.ssl.SSLParameters} in effect for this
+ * response. Returns {@code null} if this is not a HTTPS response.
+ *
+ * @return the SSLParameters associated with the response
+ */
+ public abstract SSLParameters sslParameters();
+
+ /**
+ * Returns the {@code URI} that the response was received from. This may be
+ * different from the request {@code URI} if redirection occurred.
+ *
+ * @return the URI of the response
+ */
+ public abstract URI uri();
+
+ /**
+ * Returns the HTTP protocol version that was used for this response.
+ *
+ * @return HTTP protocol version
+ */
+ public abstract HttpClient.Version version();
+
+ /**
+ * A handler for response bodies.
+ * {@Incubating}
+ * <p>
+ * This is a function that takes two parameters: the response status code,
+ * and the response headers, and which returns a {@link BodyProcessor}.
+ * The function is always called just before the response body is read. Its
+ * implementation may examine the status code or headers and must decide,
+ * whether to accept the response body or discard it, and if accepting it,
+ * exactly how to handle it.
+ * <p>
+ * Some pre-defined implementations which do not utilize the status code
+ * or headers (meaning the body is always accepted) are defined:
+ * <ul><li>{@link #asByteArray() }</li>
+ * <li>{@link #asByteArrayConsumer(java.util.function.Consumer)
+ * asByteArrayConsumer(Consumer)}</li>
+ * <li>{@link #asFileDownload(java.nio.file.Path,OpenOption...)
+ * asFileDownload(Path,OpenOption...)}</li>
+ * <li>{@link #discard(Object) }</li>
+ * <li>{@link #asString(java.nio.charset.Charset)
+ * asString(Charset)}</li></ul>
+ * <p>
+ * These implementations return the equivalent {@link BodyProcessor}.
+ * Alternatively, the handler can be used to examine the status code
+ * or headers and return different body processors as appropriate.
+ * <p>
+ * <b>Examples of handler usage</b>
+ * <p>
+ * The first example uses one of the predefined handler functions which
+ * ignore the response headers and status, and always process the response
+ * body in the same way.
+ * <pre>
+ * {@code
+ * HttpResponse<Path> resp = HttpRequest
+ * .create(URI.create("http://www.foo.com"))
+ * .GET()
+ * .response(BodyHandler.asFile(Paths.get("/tmp/f")));
+ * }
+ * </pre>
+ * Note, that even though these pre-defined handlers ignore the status code
+ * and headers, this information is still accessible from the {@code HttpResponse}
+ * when it is returned.
+ * <p>
+ * In the second example, the function returns a different processor depending
+ * on the status code.
+ * <pre>
+ * {@code
+ * HttpResponse<Path> resp1 = HttpRequest
+ * .create(URI.create("http://www.foo.com"))
+ * .GET()
+ * .response(
+ * (status, headers) -> status == 200
+ * ? BodyProcessor.asFile(Paths.get("/tmp/f"))
+ * : BodyProcessor.discard(Paths.get("/NULL")));
+ * }
+ * </pre>
+ *
+ * @param <T> the response body type.
+ */
+ @FunctionalInterface
+ public interface BodyHandler<T> {
+
+ /**
+ * Returns a {@link BodyProcessor BodyProcessor} considering the given response status
+ * code and headers. This method is always called before the body is read
+ * and its implementation can decide to keep the body and store it somewhere
+ * or else discard it, by returning the {@code BodyProcessor} returned
+ * from {@link BodyProcessor#discard(java.lang.Object) discard()}.
+ *
+ * @param statusCode the HTTP status code received
+ * @param responseHeaders the response headers received
+ * @return a response body handler
+ */
+ public BodyProcessor<T> apply(int statusCode, HttpHeaders responseHeaders);
+
+ /**
+ * Returns a response body handler which discards the response body and
+ * uses the given value as a replacement for it.
+ *
+ * @param <U> the response body type
+ * @param value the value of U to return as the body
+ * @return a response body handler
+ */
+ public static <U> BodyHandler<U> discard(U value) {
+ return (status, headers) -> BodyProcessor.discard(value);
+ }
+
+ /**
+ * Returns a {@code BodyHandler<String>} that returns a
+ * {@link BodyProcessor BodyProcessor}{@code <String>} obtained from
+ * {@link BodyProcessor#asString(java.nio.charset.Charset)
+ * BodyProcessor.asString(Charset)}. If a charset is provided, the
+ * body is decoded using it. If charset is {@code null} then the processor
+ * tries to determine the character set from the {@code Content-encoding}
+ * header. If that charset is not supported then
+ * {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8} is used.
+ *
+ * @param charset the name of the charset to interpret the body as. If
+ * {@code null} then charset determined from Content-encoding header
+ * @return a response body handler
+ */
+ public static BodyHandler<String> asString(Charset charset) {
+ return (status, headers) -> {
+ if (charset != null) {
+ return BodyProcessor.asString(charset);
+ }
+ return BodyProcessor.asString(charsetFrom(headers));
+ };
+ }
+
+
+ /**
+ * Returns a {@code BodyHandler<Path>} that returns a
+ * {@link BodyProcessor BodyProcessor}{@code <Path>} obtained from
+ * {@link BodyProcessor#asFile(Path) BodyProcessor.asFile(Path)}.
+ * <p>
+ * When the {@code HttpResponse} object is returned, the body has been completely
+ * written to the file, and {@link #body()} returns a reference to its
+ * {@link Path}.
+ *
+ * @param file the file to store the body in
+ * @return a response body handler
+ */
+ public static BodyHandler<Path> asFile(Path file) {
+ return (status, headers) -> BodyProcessor.asFile(file);
+ }
+
+ /**
+ * Returns a {@code BodyHandler<Path>} that returns a
+ * {@link BodyProcessor BodyProcessor}<{@link Path}>
+ * where the download directory is specified, but the filename is
+ * obtained from the {@code Content-Disposition} response header. The
+ * {@code Content-Disposition} header must specify the <i>attachment</i> type
+ * and must also contain a
+ * <i>filename</i> parameter. If the filename specifies multiple path
+ * components only the final component is used as the filename (with the
+ * given directory name). When the {@code HttpResponse} object is
+ * returned, the body has been completely written to the file and {@link
+ * #body()} returns a {@code Path} object for the file. The returned {@code Path} is the
+ * combination of the supplied directory name and the file name supplied
+ * by the server. If the destination directory does not exist or cannot
+ * be written to, then the response will fail with an {@link IOException}.
+ *
+ * @param directory the directory to store the file in
+ * @param openOptions open options
+ * @return a response body handler
+ */
+ public static BodyHandler<Path> asFileDownload(Path directory, OpenOption... openOptions) {
+ return (status, headers) -> {
+ String dispoHeader = headers.firstValue("Content-Disposition")
+ .orElseThrow(() -> unchecked(new IOException("No Content-Disposition")));
+ if (!dispoHeader.startsWith("attachment;")) {
+ throw unchecked(new IOException("Unknown Content-Disposition type"));
+ }
+ int n = dispoHeader.indexOf("filename=");
+ if (n == -1) {
+ throw unchecked(new IOException("Bad Content-Disposition type"));
+ }
+ int lastsemi = dispoHeader.lastIndexOf(';');
+ String disposition;
+ if (lastsemi < n) {
+ disposition = dispoHeader.substring(n + 9);
+ } else {
+ disposition = dispoHeader.substring(n + 9, lastsemi);
+ }
+ Path file = Paths.get(directory.toString(), disposition);
+ return BodyProcessor.asFile(file, openOptions);
+ };
+ }
+
+ /**
+ * Returns a {@code BodyHandler<Path>} that returns a
+ * {@link BodyProcessor BodyProcessor}{@code <Path>} obtained from
+ * {@link BodyProcessor#asFile(java.nio.file.Path, java.nio.file.OpenOption...)
+ * BodyProcessor.asFile(Path,OpenOption...)}.
+ * <p>
+ * When the {@code HttpResponse} object is returned, the body has been completely
+ * written to the file, and {@link #body()} returns a reference to its
+ * {@link Path}.
+ *
+ * @param file the filename to store the body in
+ * @param openOptions any options to use when opening/creating the file
+ * @return a response body handler
+ */
+ public static BodyHandler<Path> asFile(Path file, OpenOption... openOptions) {
+ return (status, headers) -> BodyProcessor.asFile(file, openOptions);
+ }
+
+ /**
+ * Returns a {@code BodyHandler<Void>} that returns a
+ * {@link BodyProcessor BodyProcessor}{@code <Void>} obtained from
+ * {@link BodyProcessor#asByteArrayConsumer(java.util.function.Consumer)
+ * BodyProcessor.asByteArrayConsumer(Consumer)}.
+ * <p>
+ * When the {@code HttpResponse} object is returned, the body has been completely
+ * written to the consumer.
+ *
+ * @param consumer a Consumer to accept the response body
+ * @return a response body handler
+ */
+ public static BodyHandler<Void> asByteArrayConsumer(Consumer<Optional<byte[]>> consumer) {
+ return (status, headers) -> BodyProcessor.asByteArrayConsumer(consumer);
+ }
+
+ /**
+ * Returns a {@code BodyHandler<byte[]>} that returns a
+ * {@link BodyProcessor BodyProcessor}<{@code byte[]}> obtained
+ * from {@link BodyProcessor#asByteArray() BodyProcessor.asByteArray()}.
+ * <p>
+ * When the {@code HttpResponse} object is returned, the body has been completely
+ * written to the byte array.
+ *
+ * @return a response body handler
+ */
+ public static BodyHandler<byte[]> asByteArray() {
+ return (status, headers) -> BodyProcessor.asByteArray();
+ }
+
+ /**
+ * Returns a {@code BodyHandler<String>} that returns a
+ * {@link BodyProcessor BodyProcessor}{@code <String>} obtained from
+ * {@link BodyProcessor#asString(java.nio.charset.Charset)
+ * BodyProcessor.asString(Charset)}. The body is
+ * decoded using the character set specified in
+ * the {@code Content-encoding} response header. If there is no such
+ * header, or the character set is not supported, then
+ * {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8} is used.
+ * <p>
+ * When the {@code HttpResponse} object is returned, the body has been completely
+ * written to the string.
+ *
+ * @return a response body handler
+ */
+ public static BodyHandler<String> asString() {
+ return (status, headers) -> BodyProcessor.asString(charsetFrom(headers));
+ }
+ }
+
+ /**
+ * A processor for response bodies.
+ * {@Incubating}
+ * <p>
+ * The object acts as a {@link Flow.Subscriber}<{@link ByteBuffer}> to
+ * the HTTP client implementation which publishes ByteBuffers containing the
+ * response body. The processor converts the incoming buffers of data to
+ * some user-defined object type {@code T}.
+ * <p>
+ * The {@link #getBody()} method returns a {@link CompletionStage}{@code <T>}
+ * that provides the response body object. The {@code CompletionStage} must
+ * be obtainable at any time. When it completes depends on the nature
+ * of type {@code T}. In many cases, when {@code T} represents the entire body after being
+ * read then it completes after the body has been read. If {@code T} is a streaming
+ * type such as {@link java.io.InputStream} then it completes before the
+ * body has been read, because the calling code uses it to consume the data.
+ *
+ * @param <T> the response body type
+ */
+ public interface BodyProcessor<T>
+ extends Flow.Subscriber<ByteBuffer> {
+
+ /**
+ * Returns a {@code CompletionStage} which when completed will return the
+ * response body object.
+ *
+ * @return a CompletionStage for the response body
+ */
+ public CompletionStage<T> getBody();
+
+ /**
+ * Returns a body processor which stores the response body as a {@code
+ * String} converted using the given {@code Charset}.
+ * <p>
+ * The {@link HttpResponse} using this processor is available after the
+ * entire response has been read.
+ *
+ * @param charset the character set to convert the String with
+ * @return a body processor
+ */
+ public static BodyProcessor<String> asString(Charset charset) {
+ return new ResponseProcessors.ByteArrayProcessor<>(
+ bytes -> new String(bytes, charset)
+ );
+ }
+
+ /**
+ * Returns a {@code BodyProcessor} which stores the response body as a
+ * byte array.
+ * <p>
+ * The {@link HttpResponse} using this processor is available after the
+ * entire response has been read.
+ *
+ * @return a body processor
+ */
+ public static BodyProcessor<byte[]> asByteArray() {
+ return new ResponseProcessors.ByteArrayProcessor<>(
+ Function.identity() // no conversion
+ );
+ }
+
+ /**
+ * Returns a {@code BodyProcessor} which stores the response body in a
+ * file opened with the given options and name. The file will be opened
+ * with the given options using
+ * {@link java.nio.channels.FileChannel#open(java.nio.file.Path,java.nio.file.OpenOption...)
+ * FileChannel.open} just before the body is read. Any exception thrown will be returned
+ * or thrown from {@link HttpClient#send(jdk.incubator.http.HttpRequest,
+ * jdk.incubator.http.HttpResponse.BodyHandler) HttpClient::send}
+ * or {@link HttpClient#sendAsync(jdk.incubator.http.HttpRequest,
+ * jdk.incubator.http.HttpResponse.BodyHandler) HttpClient::sendAsync}
+ * as appropriate.
+ * <p>
+ * The {@link HttpResponse} using this processor is available after the
+ * entire response has been read.
+ *
+ * @param file the file to store the body in
+ * @param openOptions the list of options to open the file with
+ * @return a body processor
+ */
+ public static BodyProcessor<Path> asFile(Path file, OpenOption... openOptions) {
+ return new ResponseProcessors.PathProcessor(file, openOptions);
+ }
+
+ /**
+ * Returns a {@code BodyProcessor} which provides the incoming body
+ * data to the provided Consumer of {@code Optional<byte[]>}. Each
+ * call to {@link Consumer#accept(java.lang.Object) Consumer.accept()}
+ * will contain a non empty {@code Optional}, except for the final invocation after
+ * all body data has been read, when the {@code Optional} will be empty.
+ * <p>
+ * The {@link HttpResponse} using this processor is available after the
+ * entire response has been read.
+ *
+ * @param consumer a Consumer of byte arrays
+ * @return a BodyProcessor
+ */
+ public static BodyProcessor<Void> asByteArrayConsumer(Consumer<Optional<byte[]>> consumer) {
+ return new ResponseProcessors.ConsumerProcessor(consumer);
+ }
+
+ /**
+ * Returns a {@code BodyProcessor} which stores the response body in a
+ * file opened with the given name. Has the same effect as calling
+ * {@link #asFile(java.nio.file.Path, java.nio.file.OpenOption...) asFile}
+ * with the standard open options {@code CREATE} and {@code WRITE}
+ * <p>
+ * The {@link HttpResponse} using this processor is available after the
+ * entire response has been read.
+ *
+ * @param file the file to store the body in
+ * @return a body processor
+ */
+ public static BodyProcessor<Path> asFile(Path file) {
+ return new ResponseProcessors.PathProcessor(
+ file,
+ StandardOpenOption.CREATE, StandardOpenOption.WRITE);
+ }
+
+ /**
+ * Returns a response processor which discards the response body. The
+ * supplied value is the value that will be returned from
+ * {@link HttpResponse#body()}.
+ *
+ * @param <U> The type of the response body
+ * @param value the value to return from HttpResponse.body()
+ * @return a {@code BodyProcessor}
+ */
+ public static <U> BodyProcessor<U> discard(U value) {
+ return new ResponseProcessors.NullProcessor<>(Optional.ofNullable(value));
+ }
+ }
+
+ /**
+ * A response processor for a HTTP/2 multi response.
+ * {@Incubating}
+ * <p>
+ * A multi response comprises a main response, and zero or more additional
+ * responses. Each additional response is sent by the server in response to
+ * requests that the server also generates. Additional responses are
+ * typically resources that the server expects the client will need which
+ * are related to the initial request.
+ * <p>
+ * Note. Instead of implementing this interface, applications should consider
+ * first using the mechanism (built on this interface) provided by
+ * {@link MultiProcessor#asMap(java.util.function.Function, boolean)
+ * MultiProcessor.asMap()} which is a slightly simplified, but
+ * general purpose interface.
+ * <p>
+ * The server generated requests are also known as <i>push promises</i>.
+ * The server is permitted to send any number of these requests up to the
+ * point where the main response is fully received. Therefore, after
+ * completion of the main response, the final number of additional
+ * responses is known. Additional responses may be canceled, but given that
+ * the server does not wait for any acknowledgment before sending the
+ * response, this must be done quickly to avoid unnecessary data transmission.
+ *
+ * <p> {@code MultiProcessor}s are parameterized with a type {@code U} which
+ * represents some meaningful aggregate of the responses received. This
+ * would typically be a collection of response or response body objects.
+ *
+ * @param <U> a type representing the aggregated results
+ * @param <T> a type representing all of the response bodies
+ *
+ * @since 9
+ */
+ public interface MultiProcessor<U,T> {
+ /**
+ * Called for the main request and each push promise that is received.
+ * The first call will always be for the main request that was sent
+ * by the caller. This {@link HttpRequest} parameter
+ * represents the initial request or subsequent PUSH_PROMISE. The
+ * implementation must return an {@code Optional} of {@link BodyHandler} for
+ * the response body. Different handlers (of the same type) can be returned
+ * for different pushes within the same multi send. If no handler
+ * (an empty {@code Optional}) is returned, then the push will be canceled. It is
+ * an error to not return a valid {@code BodyHandler} for the initial (main) request.
+ *
+ * @param request the main request or subsequent push promise
+ *
+ * @return an optional body handler
+ */
+ Optional<BodyHandler<T>> onRequest(HttpRequest request);
+
+ /**
+ * Called for each response received. For each request either one of
+ * onResponse() or onError() is guaranteed to be called, but not both.
+ *
+ * [Note] The reason for switching to this callback interface rather
+ * than using CompletableFutures supplied to onRequest() is that there
+ * is a subtle interaction between those CFs and the CF returned from
+ * completion() (or when onComplete() was called formerly). The completion()
+ * CF will not complete until after all of the work done by the onResponse()
+ * calls is done. Whereas if you just create CF's dependent on a supplied
+ * CF (to onRequest()) then the implementation has no visibility of the
+ * dependent CFs and can't guarantee to call onComplete() (or complete
+ * the completion() CF) after the dependent CFs complete.
+ *
+ * @param response the response received
+ */
+ void onResponse(HttpResponse<T> response);
+
+ /**
+ * Called if an error occurs receiving a response. For each request
+ * either one of onResponse() or onError() is guaranteed to be called,
+ * but not both.
+ *
+ * @param request the main request or subsequent push promise
+ * @param t the Throwable that caused the error
+ */
+ void onError(HttpRequest request, Throwable t);
+
+ /**
+ * Returns a {@link java.util.concurrent.CompletableFuture}{@code <U>}
+ * which completes when the aggregate result object itself is available.
+ * It is expected that the returned {@code CompletableFuture} will depend
+ * on one of the given {@code CompletableFuture<Void}s which themselves complete
+ * after all individual responses associated with the multi response
+ * have completed, or after all push promises have been received.
+ *
+ * @implNote Implementations might follow the pattern shown below
+ * <pre>
+ * {@code
+ * CompletableFuture<U> completion(
+ * CompletableFuture<Void> onComplete,
+ * CompletableFuture<Void> onFinalPushPromise)
+ * {
+ * return onComplete.thenApply((v) -> {
+ * U u = ... instantiate and populate a U instance
+ * return u;
+ * });
+ * }
+ * }
+ * </pre>
+ *
+ * @param onComplete a CompletableFuture which completes after all
+ * responses have been received relating to this multi request.
+ *
+ * @param onFinalPushPromise CompletableFuture which completes after all
+ * push promises have been received.
+ *
+ * @return the aggregate CF response object
+ */
+ CompletableFuture<U> completion(CompletableFuture<Void> onComplete,
+ CompletableFuture<Void> onFinalPushPromise);
+
+ /**
+ * Returns a general purpose handler for multi responses. The aggregated
+ * result object produced by this handler is a
+ * {@code Map<HttpRequest,CompletableFuture<HttpResponse<V>>>}. Each
+ * request (both the original user generated request and each server
+ * generated push promise) is returned as a key of the map. The value
+ * corresponding to each key is a
+ * {@code CompletableFuture<HttpResponse<V>>}.
+ * <p>
+ * There are two ways to use these handlers, depending on the value of
+ * the <i>completion</I> parameter. If completion is true, then the
+ * aggregated result will be available after all responses have
+ * themselves completed. If <i>completion</i> is false, then the
+ * aggregated result will be available immediately after the last push
+ * promise was received. In the former case, this implies that all the
+ * CompletableFutures in the map values will have completed. In the
+ * latter case, they may or may not have completed yet.
+ * <p>
+ * The simplest way to use these handlers is to set completion to
+ * {@code true}, and then all (results) values in the Map will be
+ * accessible without blocking.
+ * <p>
+ * See {@link #asMap(java.util.function.Function, boolean)
+ * }
+ * for a code sample of using this interface.
+ *
+ * @param <V> the body type used for all responses
+ * @param pushHandler a function invoked for each request or push
+ * promise
+ * @param completion {@code true} if the aggregate CompletableFuture
+ * completes after all responses have been received, or {@code false}
+ * after all push promises received.
+ *
+ * @return a MultiProcessor
+ */
+ public static <V> MultiProcessor<MultiMapResult<V>,V> asMap(
+ Function<HttpRequest, Optional<HttpResponse.BodyHandler<V>>> pushHandler,
+ boolean completion) {
+
+ return new MultiProcessorImpl<V>(pushHandler, completion);
+ }
+
+ /**
+ * Returns a general purpose handler for multi responses. This is a
+ * convenience method which invokes {@link #asMap(java.util.function.Function,boolean)
+ * asMap(Function, true)} meaning that the aggregate result
+ * object completes after all responses have been received.
+ * <p>
+ * <b>Example usage:</b>
+ * <br>
+ * <pre>
+ * {@code
+ * HttpRequest request = HttpRequest.newBuilder()
+ * .uri(URI.create("https://www.foo.com/"))
+ * .GET()
+ * .build();
+ *
+ * HttpClient client = HttpClient.newHttpClient();
+ *
+ * Map<HttpRequest,CompletableFuture<HttpResponse<String>>> results = client
+ * .sendAsync(request, MultiProcessor.asMap(
+ * (req) -> Optional.of(HttpResponse.BodyHandler.asString())))
+ * .join();
+ * }</pre>
+ * <p>
+ * The lambda in this example is the simplest possible implementation,
+ * where neither the incoming requests are examined, nor the response
+ * headers, and every push that the server sends is accepted. When the
+ * join() call returns, all {@code HttpResponse}s and their associated
+ * body objects are available.
+ *
+ * @param <V> the body type used for all responses
+ * @param pushHandler a function invoked for each request or push
+ * promise
+ * @return a MultiProcessor
+ */
+ public static <V> MultiProcessor<MultiMapResult<V>,V> asMap(
+ Function<HttpRequest, Optional<HttpResponse.BodyHandler<V>>> pushHandler) {
+
+ return asMap(pushHandler, true);
+ }
+
+ }
+}