src/jdk.incubator.httpclient/share/classes/jdk/incubator/http/HttpResponse.java
author dfuchs
Thu, 23 Nov 2017 10:21:19 +0000
branchhttp-client-branch
changeset 55860 dc4a39bc1517
parent 55858 cd5eeec735fb
child 55869 54f89370f26a
permissions -rw-r--r--
http-client-branch: review comments add missing links to pre-defined BodyHandlers
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     1
/*
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
     2
 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     3
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     4
 *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     5
 * This code is free software; you can redistribute it and/or modify it
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     6
 * under the terms of the GNU General Public License version 2 only, as
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     7
 * published by the Free Software Foundation.  Oracle designates this
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     8
 * particular file as subject to the "Classpath" exception as provided
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
     9
 * by Oracle in the LICENSE file that accompanied this code.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    10
 *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    11
 * This code is distributed in the hope that it will be useful, but WITHOUT
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    12
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    13
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    14
 * version 2 for more details (a copy is included in the LICENSE file that
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    15
 * accompanied this code).
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    16
 *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    17
 * You should have received a copy of the GNU General Public License version
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    18
 * 2 along with this work; if not, write to the Free Software Foundation,
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    19
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    20
 *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    21
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    22
 * or visit www.oracle.com if you need additional information or have any
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    23
 * questions.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    24
 */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    25
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    26
package jdk.incubator.http;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    27
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    28
import java.io.IOException;
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    29
import java.io.InputStream;
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    30
import java.net.URI;
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    31
import jdk.incubator.http.ResponseSubscribers.MultiSubscriberImpl;
43730
b6847c320451 8174745: Httpclient source update for JDK 8
michaelm
parents: 43302
diff changeset
    32
import static jdk.incubator.http.internal.common.Utils.unchecked;
b6847c320451 8174745: Httpclient source update for JDK 8
michaelm
parents: 43302
diff changeset
    33
import static jdk.incubator.http.internal.common.Utils.charsetFrom;
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    34
import java.nio.ByteBuffer;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    35
import java.nio.charset.Charset;
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    36
import java.nio.channels.FileChannel;
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    37
import java.nio.file.OpenOption;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    38
import java.nio.file.Path;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    39
import java.nio.file.Paths;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    40
import java.nio.file.StandardOpenOption;
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    41
import java.security.AccessControlContext;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    42
import java.util.Arrays;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    43
import java.util.List;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    44
import java.util.Objects;
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    45
import java.util.Optional;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    46
import java.util.concurrent.CompletableFuture;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    47
import java.util.concurrent.CompletionStage;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    48
import java.util.concurrent.Flow;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    49
import java.util.function.Consumer;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    50
import java.util.function.Function;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    51
import javax.net.ssl.SSLParameters;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    52
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    53
/**
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    54
 * Represents a response to a {@link HttpRequest}.
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    55
 * {@Incubating}
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    56
 *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    57
 * <p> A {@code HttpResponse} is available when the response status code and
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    58
 * headers have been received, and typically after the response body has also
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    59
 * been received. This depends on the response body handler provided when
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    60
 * sending the request. In all cases, the response body handler is invoked
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    61
 * before the body is read. This gives applications an opportunity to decide
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
    62
 * how to handle the body.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    63
 *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    64
 * <p> Methods are provided in this class for accessing the response headers,
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    65
 * and response body.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    66
 *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    67
 * <p><b>Response handlers and subscribers</b>
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    68
 *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    69
 * <p> Response bodies are handled at two levels. Application code supplies a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    70
 * response handler ({@link BodyHandler}) which may examine the response status
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    71
 * code and headers, and which then returns a {@link BodySubscriber} to actually
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    72
 * read (or discard) the body and convert it into some useful Java object type.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    73
 * The handler can return one of the pre-defined subscriber types, or a custom
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    74
 * subscriber, or if the body is to be discarded it can call {@link
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    75
 * BodySubscriber#discard(Object) discard} and return a subscriber which
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    76
 * discards the response body. Static implementations of both handlers and
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    77
 * subscribers are provided in {@linkplain BodyHandler BodyHandler} and
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    78
 * {@linkplain BodySubscriber BodySubscriber} respectively. In all cases, the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    79
 * handler functions provided are convenience implementations which ignore the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    80
 * supplied status code and headers and return the relevant pre-defined {@code
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    81
 * BodySubscriber}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    82
 *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
    83
 * <p> See {@link BodyHandler} for example usage.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    84
 *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    85
 * @param <T> the response body type
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    86
 * @since 9
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    87
 */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    88
public abstract class HttpResponse<T> {
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    89
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    90
    /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    91
     * Creates an HttpResponse.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    92
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    93
    protected HttpResponse() { }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    94
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    95
    /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    96
     * Returns the status code for this response.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    97
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    98
     * @return the response code
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
    99
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   100
    public abstract int statusCode();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   101
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   102
    /**
55852
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   103
     * Returns the {@link HttpRequest} corresponding to this response.
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   104
     *
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   105
     * <p> This may not be the original request provided by the caller,
55852
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   106
     * for example, if that request was redirected.
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   107
     *
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   108
     * @see #previousResponse()
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   109
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   110
     * @return the request
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   111
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   112
    public abstract HttpRequest request();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   113
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   114
    /**
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   115
     * Returns an {@code Optional} containing the previous intermediate response
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   116
     * if one was received. An intermediate response is one that is received
55852
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   117
     * as a result of redirection or authentication. If no previous response
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   118
     * was received then an empty {@code Optional} is returned.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   119
     *
55852
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   120
     * @return an Optional containing the HttpResponse, if any.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   121
     */
55852
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   122
    public abstract Optional<HttpResponse<T>> previousResponse();
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   123
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   124
    /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   125
     * Returns the received response headers.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   126
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   127
     * @return the response headers
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   128
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   129
    public abstract HttpHeaders headers();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   130
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   131
    /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   132
     * Returns the body. Depending on the type of {@code T}, the returned body
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   133
     * may represent the body after it was read (such as {@code byte[]}, or
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   134
     * {@code String}, or {@code Path}) or it may represent an object with
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   135
     * which the body is read, such as an {@link java.io.InputStream}.
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   136
     *
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   137
     * <p> If this {@code HttpResponse} was returned from an invocation of
55852
32f6aefec11e http-client-branch: HttpRequest/HttpResponse api change: remove link between requests, add links between responses. Fixed some redirection problems
michaelm
parents: 55839
diff changeset
   138
     * {@link #previousResponse()} then this method returns {@code null}
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   139
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   140
     * @return the body
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   141
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   142
    public abstract T body();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   143
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   144
    /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   145
     * Returns the {@link javax.net.ssl.SSLParameters} in effect for this
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   146
     * response. Returns {@code null} if this is not a HTTPS response.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   147
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   148
     * @return the SSLParameters associated with the response
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   149
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   150
    public abstract SSLParameters sslParameters();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   151
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   152
    /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   153
     * Returns the {@code URI} that the response was received from. This may be
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   154
     * different from the request {@code URI} if redirection occurred.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   155
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   156
     * @return the URI of the response
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   157
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   158
    public abstract URI uri();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   159
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   160
    /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   161
     * Returns the HTTP protocol version that was used for this response.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   162
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   163
     * @return HTTP protocol version
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   164
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   165
    public abstract HttpClient.Version version();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   166
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   167
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   168
    private static String pathForSecurityCheck(Path path) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   169
        return path.toFile().getPath();
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   170
    }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   171
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   172
    /** A body handler that is further restricted by a given ACC. */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   173
    interface UntrustedBodyHandler<T> extends BodyHandler<T> {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   174
        void setAccessControlContext(AccessControlContext acc);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   175
    }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   176
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   177
    /**
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   178
     * A Path body handler.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   179
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   180
     * Note: Exists mainly too allow setting of the senders ACC post creation of
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   181
     * the handler.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   182
     */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   183
    static class PathBodyHandler implements UntrustedBodyHandler<Path> {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   184
        private final Path file;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   185
        private final OpenOption[]openOptions;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   186
        private volatile AccessControlContext acc;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   187
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   188
        PathBodyHandler(Path file, OpenOption... openOptions) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   189
            this.file = file;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   190
            this.openOptions = openOptions;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   191
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   192
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   193
        @Override
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   194
        public void setAccessControlContext(AccessControlContext acc) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   195
            this.acc = acc;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   196
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   197
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   198
        @Override
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   199
        public BodySubscriber<Path> apply(int statusCode, HttpHeaders headers) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   200
            ResponseSubscribers.PathSubscriber bs = (ResponseSubscribers.PathSubscriber)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   201
                    BodySubscriber.asFileImpl(file, openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   202
            bs.setAccessControlContext(acc);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   203
            return bs;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   204
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   205
    }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   206
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   207
    // Similar to Path body handler, but for file download. Supports setting ACC.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   208
    static class FileDownloadBodyHandler implements UntrustedBodyHandler<Path> {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   209
        private final Path directory;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   210
        private final OpenOption[]openOptions;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   211
        private volatile AccessControlContext acc;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   212
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   213
        FileDownloadBodyHandler(Path directory, OpenOption... openOptions) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   214
            this.directory = directory;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   215
            this.openOptions = openOptions;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   216
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   217
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   218
        @Override
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   219
        public void setAccessControlContext(AccessControlContext acc) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   220
            this.acc = acc;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   221
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   222
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   223
        @Override
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   224
        public BodySubscriber<Path> apply(int statusCode, HttpHeaders headers) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   225
            String dispoHeader = headers.firstValue("Content-Disposition")
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   226
                    .orElseThrow(() -> unchecked(new IOException("No Content-Disposition")));
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   227
            if (!dispoHeader.startsWith("attachment;")) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   228
                throw unchecked(new IOException("Unknown Content-Disposition type"));
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   229
            }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   230
            int n = dispoHeader.indexOf("filename=");
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   231
            if (n == -1) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   232
                throw unchecked(new IOException("Bad Content-Disposition type"));
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   233
            }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   234
            int lastsemi = dispoHeader.lastIndexOf(';');
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   235
            String disposition;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   236
            if (lastsemi < n) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   237
                disposition = dispoHeader.substring(n + 9);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   238
            } else {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   239
                disposition = dispoHeader.substring(n + 9, lastsemi);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   240
            }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   241
            Path file = Paths.get(directory.toString(), disposition);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   242
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   243
            ResponseSubscribers.PathSubscriber bs = (ResponseSubscribers.PathSubscriber)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   244
                    BodySubscriber.asFileImpl(file, openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   245
            bs.setAccessControlContext(acc);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   246
            return bs;
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   247
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   248
    }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   249
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   250
    /**
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   251
     * A handler for response bodies.
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   252
     * {@Incubating}
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   253
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   254
     * <p> This is a function that takes two parameters: the response status code,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   255
     * and the response headers, and which returns a {@linkplain BodySubscriber}.
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   256
     * The function is always called just before the response body is read. Its
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   257
     * implementation may examine the status code or headers and must decide,
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   258
     * whether to accept the response body or discard it, and if accepting it,
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   259
     * exactly how to handle it.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   260
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   261
     * <p> Some pre-defined implementations which do not utilize the status code
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   262
     * or headers (meaning the body is always accepted) are defined:
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   263
     * <ul><li>{@link #asByteArray() }</li>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   264
     * <li>{@link #asByteArrayConsumer(java.util.function.Consumer)
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   265
     * asByteArrayConsumer(Consumer)}</li>
55860
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   266
     * <li>{@link #asString(java.nio.charset.Charset) asString(Charset)}</li>
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   267
     * <li>{@link #asFile(Path, OpenOption...)
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   268
     * asFile(Path,OpenOption...)}</li>
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   269
     * <li>{@link #asFileDownload(java.nio.file.Path,OpenOption...)
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   270
     * asFileDownload(Path,OpenOption...)}</li>
55860
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   271
     * <li>{@link #asInputStream() asInputStream()}</li>
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   272
     * <li>{@link #discard(Object) }</li>
55860
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   273
     * <li>{@link #buffering(BodyHandler, int)
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   274
     * buffering(BodyHandler,int)}</li>
dc4a39bc1517 http-client-branch: review comments add missing links to pre-defined BodyHandlers
dfuchs
parents: 55858
diff changeset
   275
     * </ul>
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   276
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   277
     * <p> These implementations return the equivalent {@link BodySubscriber}.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   278
     * Alternatively, the handler can be used to examine the status code
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   279
     * or headers and return different body subscribers as appropriate.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   280
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   281
     * <p><b>Examples of handler usage</b>
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   282
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   283
     * <p> The first example uses one of the predefined handler functions which
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   284
     * ignores the response headers and status, and always process the response
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   285
     * body in the same way.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   286
     * <pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   287
     * {@code
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   288
     *      HttpResponse<Path> resp = HttpRequest
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   289
     *              .create(URI.create("http://www.foo.com"))
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   290
     *              .GET()
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   291
     *              .response(BodyHandler.asFile(Paths.get("/tmp/f")));
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   292
     * }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   293
     * </pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   294
     * Note, that even though these pre-defined handlers ignore the status code
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   295
     * and headers, this information is still accessible from the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   296
     * {@code HttpResponse} when it is returned.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   297
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   298
     * <p> In the second example, the function returns a different subscriber
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   299
     * depending on the status code.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   300
     * <pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   301
     * {@code
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   302
     *      HttpResponse<Path> resp1 = HttpRequest
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   303
     *              .create(URI.create("http://www.foo.com"))
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   304
     *              .GET()
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   305
     *              .response(
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   306
     *                  (status, headers) -> status == 200
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   307
     *                      ? BodySubscriber.asFile(Paths.get("/tmp/f"))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   308
     *                      : BodySubscriber.discard(Paths.get("/NULL")));
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   309
     * }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   310
     * </pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   311
     *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   312
     * @param <T> the response body type
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   313
     */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   314
    @FunctionalInterface
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   315
    public interface BodyHandler<T> {
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   316
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   317
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   318
         * Returns a {@link BodySubscriber BodySubscriber} considering the given
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   319
         * response status code and headers. This method is always called before
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   320
         * the body is read and its implementation can decide to keep the body
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   321
         * and store it somewhere, or else discard it by returning the {@code
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   322
         * BodySubscriber} returned from {@link BodySubscriber#discard(Object)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   323
         * discard}.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   324
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   325
         * @param statusCode the HTTP status code received
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   326
         * @param responseHeaders the response headers received
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   327
         * @return a body subscriber
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   328
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   329
        public BodySubscriber<T> apply(int statusCode, HttpHeaders responseHeaders);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   330
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   331
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   332
         * Returns a response body handler which discards the response body and
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   333
         * uses the given value as a replacement for it.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   334
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   335
         * @param <U> the response body type
55839
d4142ab48c8a http-client-branch: minor doc formatting
dfuchs
parents: 55837
diff changeset
   336
         * @param value the value of U to return as the body, may be {@code null}
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   337
         * @return a response body handler
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   338
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   339
        public static <U> BodyHandler<U> discard(U value) {
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   340
            return (status, headers) -> BodySubscriber.discard(value);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   341
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   342
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   343
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   344
         * Returns a {@code BodyHandler<String>} that returns a
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   345
         * {@link BodySubscriber BodySubscriber}{@code <String>} obtained from
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   346
         * {@link BodySubscriber#asString(Charset) BodySubscriber.asString(Charset)}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   347
         * If a charset is provided, the body is decoded using it. If charset is
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   348
         * {@code null} then the handler tries to determine the character set
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   349
         * from the {@code Content-encoding} header. If that charset is not
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   350
         * supported then {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   351
         * is used.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   352
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   353
         * @param charset The name of the charset to interpret the body as. If
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   354
         *                {@code null} then the charset is determined from the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   355
         *                <i>Content-encoding</i> header.
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   356
         * @return a response body handler
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   357
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   358
        public static BodyHandler<String> asString(Charset charset) {
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   359
            return (status, headers) -> {
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   360
                if (charset != null) {
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   361
                    return BodySubscriber.asString(charset);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   362
                }
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   363
                return BodySubscriber.asString(charsetFrom(headers));
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   364
            };
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   365
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   366
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   367
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   368
         * Returns a {@code BodyHandler<Path>} that returns a
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   369
         * {@link BodySubscriber BodySubscriber}{@code <Path>} obtained from
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   370
         * {@link BodySubscriber#asFile(Path, OpenOption...)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   371
         * BodySubscriber.asFile(Path,OpenOption...)}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   372
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   373
         * <p> When the {@code HttpResponse} object is returned, the body has
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   374
         * been completely written to the file, and {@link #body()} returns a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   375
         * reference to its {@link Path}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   376
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   377
         * @param file the filename to store the body in
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   378
         * @param openOptions any options to use when opening/creating the file
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   379
         * @return a response body handler
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   380
         * @throws SecurityException If a security manager has been installed
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   381
         *          and it denies {@link SecurityManager#checkWrite(String)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   382
         *          write access} to the file. The {@link
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   383
         *          SecurityManager#checkDelete(String) checkDelete} method is
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   384
         *          invoked to check delete access if the file is opened with
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   385
         *          the {@code DELETE_ON_CLOSE} option.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   386
         */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   387
        public static BodyHandler<Path> asFile(Path file, OpenOption... openOptions) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   388
            Objects.requireNonNull(file);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   389
            SecurityManager sm = System.getSecurityManager();
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   390
            if (sm != null) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   391
                String fn = pathForSecurityCheck(file);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   392
                sm.checkWrite(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   393
                List<OpenOption> opts = Arrays.asList(openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   394
                if (opts.contains(StandardOpenOption.DELETE_ON_CLOSE))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   395
                    sm.checkDelete(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   396
                if (opts.contains(StandardOpenOption.READ))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   397
                    sm.checkRead(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   398
            }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   399
            return new PathBodyHandler(file, openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   400
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   401
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   402
        /**
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   403
         * Returns a {@code BodyHandler<Path>} that returns a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   404
         * {@link BodySubscriber BodySubscriber}{@code <Path>} obtained from
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   405
         * {@link BodySubscriber#asFile(Path) BodySubscriber.asFile(Path)}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   406
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   407
         * <p> When the {@code HttpResponse} object is returned, the body has
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   408
         * been completely written to the file, and {@link #body()} returns a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   409
         * reference to its {@link Path}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   410
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   411
         * @param file the file to store the body in
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   412
         * @return a response body handler
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   413
         * @throws SecurityException if a security manager has been installed
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   414
         *          and it denies {@link SecurityManager#checkWrite(String)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   415
         *          write access} to the file
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   416
         */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   417
        public static BodyHandler<Path> asFile(Path file) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   418
            return BodyHandler.asFile(file, StandardOpenOption.CREATE,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   419
                                            StandardOpenOption.WRITE);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   420
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   421
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   422
        /**
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   423
         * Returns a {@code BodyHandler<Path>} that returns a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   424
         * {@link BodySubscriber BodySubscriber}&lt;{@link Path}&gt;
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   425
         * where the download directory is specified, but the filename is
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   426
         * obtained from the {@code Content-Disposition} response header. The
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   427
         * {@code Content-Disposition} header must specify the <i>attachment</i>
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   428
         * type and must also contain a <i>filename</i> parameter. If the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   429
         * filename specifies multiple path components only the final component
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   430
         * is used as the filename (with the given directory name).
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   431
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   432
         * <p> When the {@code HttpResponse} object is returned, the body has
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   433
         * been completely written to the file and {@link #body()} returns a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   434
         * {@code Path} object for the file. The returned {@code Path} is the
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   435
         * combination of the supplied directory name and the file name supplied
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   436
         * by the server. If the destination directory does not exist or cannot
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   437
         * be written to, then the response will fail with an {@link IOException}.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   438
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   439
         * @param directory the directory to store the file in
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   440
         * @param openOptions open options
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   441
         * @return a response body handler
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   442
         * @throws SecurityException If a security manager has been installed
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   443
         *          and it denies {@link SecurityManager#checkWrite(String)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   444
         *          write access} to the file. The {@link
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   445
         *          SecurityManager#checkDelete(String) checkDelete} method is
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   446
         *          invoked to check delete access if the file is opened with
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   447
         *          the {@code DELETE_ON_CLOSE} option.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   448
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   449
         //####: check if the dir exists and is writable??
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   450
        public static BodyHandler<Path> asFileDownload(Path directory,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   451
                                                       OpenOption... openOptions) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   452
            Objects.requireNonNull(directory);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   453
            SecurityManager sm = System.getSecurityManager();
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   454
            if (sm != null) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   455
                String fn = pathForSecurityCheck(directory);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   456
                sm.checkWrite(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   457
                List<OpenOption> opts = Arrays.asList(openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   458
                if (opts.contains(StandardOpenOption.DELETE_ON_CLOSE))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   459
                    sm.checkDelete(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   460
                if (opts.contains(StandardOpenOption.READ))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   461
                    sm.checkRead(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   462
            }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   463
            return new FileDownloadBodyHandler(directory, openOptions);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   464
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   465
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   466
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   467
         * Returns a {@code BodyHandler<InputStream>} that returns a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   468
         * {@link BodySubscriber BodySubscriber}{@code <InputStream>} obtained
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   469
         * from {@link BodySubscriber#asInputStream() BodySubscriber.asInputStream}.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   470
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   471
         * <p> When the {@code HttpResponse} object is returned, the response
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   472
         * headers will have been completely read, but the body may not have
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   473
         * been fully received yet. The {@link #body()} method returns an
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   474
         * {@link InputStream} from which the body can be read as it is received.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   475
         *
55858
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   476
         * @apiNote See {@link BodySubscriber#asInputStream()} for more information.
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   477
         *
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   478
         * @return a response body handler
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   479
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   480
        public static BodyHandler<InputStream> asInputStream() {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   481
            return (status, headers) -> BodySubscriber.asInputStream();
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   482
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   483
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   484
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   485
         * Returns a {@code BodyHandler<Void>} that returns a
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   486
         * {@link BodySubscriber BodySubscriber}{@code <Void>} obtained from
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   487
         * {@link BodySubscriber#asByteArrayConsumer(Consumer)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   488
         * BodySubscriber.asByteArrayConsumer(Consumer)}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   489
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   490
         * <p> When the {@code HttpResponse} object is returned, the body has
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   491
         * been completely written to the consumer.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   492
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   493
         * @param consumer a Consumer to accept the response body
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   494
         * @return a response body handler
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   495
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   496
        public static BodyHandler<Void> asByteArrayConsumer(Consumer<Optional<byte[]>> consumer) {
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   497
            return (status, headers) -> BodySubscriber.asByteArrayConsumer(consumer);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   498
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   499
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   500
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   501
         * Returns a {@code BodyHandler<byte[]>} that returns a
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   502
         * {@link BodySubscriber BodySubscriber}&lt;{@code byte[]}&gt; obtained
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   503
         * from {@link BodySubscriber#asByteArray() BodySubscriber.asByteArray()}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   504
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   505
         * <p> When the {@code HttpResponse} object is returned, the body has
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   506
         * been completely written to the byte array.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   507
         *
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   508
         * @return a response body handler
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   509
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   510
        public static BodyHandler<byte[]> asByteArray() {
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   511
            return (status, headers) -> BodySubscriber.asByteArray();
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   512
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   513
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   514
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   515
         * Returns a {@code BodyHandler<String>} that returns a
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   516
         * {@link BodySubscriber BodySubscriber}{@code <String>} obtained from
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   517
         * {@link BodySubscriber#asString(java.nio.charset.Charset)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   518
         * BodySubscriber.asString(Charset)}. The body is
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   519
         * decoded using the character set specified in
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   520
         * the {@code Content-encoding} response header. If there is no such
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   521
         * header, or the character set is not supported, then
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   522
         * {@link java.nio.charset.StandardCharsets#UTF_8 UTF_8} is used.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   523
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   524
         * <p> When the {@code HttpResponse} object is returned, the body has
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   525
         * been completely written to the string.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   526
         *
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   527
         * @return a response body handler
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   528
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   529
        public static BodyHandler<String> asString() {
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   530
            return (status, headers) -> BodySubscriber.asString(charsetFrom(headers));
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   531
        }
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   532
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   533
        /**
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   534
         * Returns a {@code BodyHandler} which, when invoked, returns a {@linkplain
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   535
         * BodySubscriber#buffering(BodySubscriber,int) buffering BodySubscriber}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   536
         * that buffers data before delivering it to the downstream subscriber.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   537
         * These {@code BodySubscriber} instances are created by calling
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   538
         * {@linkplain BodySubscriber#buffering(BodySubscriber,int)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   539
         * BodySubscriber.buffering} with a subscriber obtained from the given
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   540
         * downstream handler and the {@code bufferSize} parameter.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   541
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   542
         * @param downstreamHandler the downstream handler
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   543
         * @param bufferSize the buffer size parameter passed to {@linkplain
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   544
         *        BodySubscriber#buffering(BodySubscriber,int) BodySubscriber.buffering}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   545
         * @return a body handler
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   546
         * @throws IllegalArgumentException if {@code bufferSize <= 0}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   547
         */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   548
         public static <T> BodyHandler<T> buffering(BodyHandler<T> downstreamHandler,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   549
                                                    int bufferSize) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   550
             if (bufferSize <= 0)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   551
                 throw new IllegalArgumentException("must be greater than 0");
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   552
             return (status, headers) -> BodySubscriber
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   553
                     .buffering(downstreamHandler.apply(status, headers),
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   554
                                bufferSize);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   555
         }
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   556
    }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   557
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   558
    /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   559
     * A subscriber for response bodies.
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   560
     * {@Incubating}
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   561
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   562
     * <p> The object acts as a {@link Flow.Subscriber}&lt;{@link List}&lt;{@link
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   563
     * ByteBuffer}&gt;&gt; to the HTTP client implementation, which publishes
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   564
     * unmodifiable lists of ByteBuffers containing the response body. The Flow
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   565
     * of data, as well as the order of ByteBuffers in the Flow lists, is a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   566
     * strictly ordered representation of the response body. Both the Lists and
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   567
     * the ByteBuffers, once passed to the subscriber, are no longer used by the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   568
     * HTTP client. The subscriber converts the incoming buffers of data to some
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   569
     * user-defined object type {@code T}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   570
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   571
     * <p> The {@link #getBody()} method returns a {@link CompletionStage}{@code
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   572
     * <T>} that provides the response body object. The {@code CompletionStage}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   573
     * must be obtainable at any time. When it completes depends on the nature
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   574
     * of type {@code T}. In many cases, when {@code T} represents the entire
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   575
     * body after being read then it completes after the body has been read. If
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   576
     * {@code T} is a streaming type such as {@link java.io.InputStream} then it
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   577
     * completes before the body has been read, because the calling code uses it
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   578
     * to consume the data.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   579
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   580
     * @param <T> the response body type
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   581
     */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   582
    public interface BodySubscriber<T>
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   583
            extends Flow.Subscriber<List<ByteBuffer>> {
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   584
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   585
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   586
         * Returns a {@code CompletionStage} which when completed will return
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   587
         * the response body object.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   588
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   589
         * @return a CompletionStage for the response body
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   590
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   591
        public CompletionStage<T> getBody();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   592
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   593
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   594
         * Returns a body subscriber which stores the response body as a {@code
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   595
         * String} converted using the given {@code Charset}.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   596
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   597
         * <p> The {@link HttpResponse} using this subscriber is available after
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   598
         * the entire response has been read.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   599
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   600
         * @param charset the character set to convert the String with
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   601
         * @return a body subscriber
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   602
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   603
        public static BodySubscriber<String> asString(Charset charset) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   604
            return new ResponseSubscribers.ByteArraySubscriber<>(
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   605
                    bytes -> new String(bytes, charset)
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   606
            );
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   607
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   608
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   609
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   610
         * Returns a {@code BodySubscriber} which stores the response body as a
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   611
         * byte array.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   612
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   613
         * <p> The {@link HttpResponse} using this subscriber is available after
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   614
         * the entire response has been read.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   615
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   616
         * @return a body subscriber
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   617
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   618
        public static BodySubscriber<byte[]> asByteArray() {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   619
            return new ResponseSubscribers.ByteArraySubscriber<>(
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   620
                    Function.identity() // no conversion
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   621
            );
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   622
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   623
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   624
        // no security check
55837
0262f29eef0d http-client-branch: review comment asFileImpl sneaked into the API
chegar
parents: 55810
diff changeset
   625
        private static BodySubscriber<Path> asFileImpl(Path file, OpenOption... openOptions) {
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   626
            return new ResponseSubscribers.PathSubscriber(file, openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   627
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   628
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   629
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   630
         * Returns a {@code BodySubscriber} which stores the response body in a
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   631
         * file opened with the given options and name. The file will be opened
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   632
         * with the given options using {@link FileChannel#open(Path,OpenOption...)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   633
         * FileChannel.open} just before the body is read. Any exception thrown
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   634
         * will be returned or thrown from {@link HttpClient#send(HttpRequest,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   635
         * BodyHandler) HttpClient::send} or {@link HttpClient#sendAsync(HttpRequest,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   636
         * BodyHandler) HttpClient::sendAsync} as appropriate.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   637
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   638
         * <p> The {@link HttpResponse} using this subscriber is available after
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   639
         * the entire response has been read.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   640
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   641
         * @param file the file to store the body in
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   642
         * @param openOptions the list of options to open the file with
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   643
         * @return a body subscriber
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   644
         * @throws SecurityException If a security manager has been installed
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   645
         *          and it denies {@link SecurityManager#checkWrite(String)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   646
         *          write access} to the file. The {@link
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   647
         *          SecurityManager#checkDelete(String) checkDelete} method is
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   648
         *          invoked to check delete access if the file is opened with the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   649
         *          {@code DELETE_ON_CLOSE} option.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   650
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   651
        public static BodySubscriber<Path> asFile(Path file, OpenOption... openOptions) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   652
            Objects.requireNonNull(file);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   653
            SecurityManager sm = System.getSecurityManager();
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   654
            if (sm != null) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   655
                String fn = pathForSecurityCheck(file);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   656
                sm.checkWrite(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   657
                List<OpenOption> opts = Arrays.asList(openOptions);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   658
                if (opts.contains(StandardOpenOption.DELETE_ON_CLOSE))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   659
                    sm.checkDelete(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   660
                if (opts.contains(StandardOpenOption.READ))
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   661
                    sm.checkRead(fn);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   662
            }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   663
            return asFileImpl(file, openOptions);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   664
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   665
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   666
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   667
         * Returns a {@code BodySubscriber} which stores the response body in a
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   668
         * file opened with the given name. Has the same effect as calling
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   669
         * {@link #asFile(Path, OpenOption...) asFile} with the standard open
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   670
         * options {@code CREATE} and {@code WRITE}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   671
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   672
         * <p> The {@link HttpResponse} using this subscriber is available after
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   673
         * the entire response has been read.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   674
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   675
         * @param file the file to store the body in
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   676
         * @return a body subscriber
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   677
         * @throws SecurityException if a security manager has been installed
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   678
         *          and it denies {@link SecurityManager#checkWrite(String)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   679
         *          write access} to the file
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   680
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   681
        public static BodySubscriber<Path> asFile(Path file) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   682
            return asFile(file, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   683
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   684
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   685
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   686
         * Returns a {@code BodySubscriber} which provides the incoming body
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   687
         * data to the provided Consumer of {@code Optional<byte[]>}. Each
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   688
         * call to {@link Consumer#accept(java.lang.Object) Consumer.accept()}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   689
         * will contain a non empty {@code Optional}, except for the final
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   690
         * invocation after all body data has been read, when the {@code
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   691
         * Optional} will be empty.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   692
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   693
         * <p> The {@link HttpResponse} using this subscriber is available after
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   694
         * the entire response has been read.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   695
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   696
         * @param consumer a Consumer of byte arrays
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   697
         * @return a BodySubscriber
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   698
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   699
        public static BodySubscriber<Void> asByteArrayConsumer(Consumer<Optional<byte[]>> consumer) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   700
            return new ResponseSubscribers.ConsumerSubscriber(consumer);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   701
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   702
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   703
        /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   704
         * Returns a {@code BodySubscriber} which streams the response body as
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   705
         * an {@link InputStream}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   706
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   707
         * <p> The {@link HttpResponse} using this subscriber is available
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   708
         * immediately after the response headers have been read, without
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   709
         * requiring to wait for the entire body to be processed. The response
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   710
         * body can then be read directly from the {@link InputStream}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   711
         *
55858
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   712
         * @apiNote To ensure that all resources associated with the
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   713
         * corresponding exchange are properly released the caller must
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   714
         * ensure to either read all bytes until EOF is reached, or call
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   715
         * {@link InputStream#close} if it is unable or unwilling to do so.
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   716
         * Calling {@code close} before exhausting the stream may cause
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   717
         * the underlying HTTP connection to be closed and prevent it
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   718
         * from being reused for subsequent operations.
cd5eeec735fb http-client-branch: review comment BodySubscriber::asInputStream
dfuchs
parents: 55855
diff changeset
   719
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   720
         * @return a body subscriber that streams the response body as an
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   721
         *         {@link InputStream}.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   722
         */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   723
        public static BodySubscriber<InputStream> asInputStream() {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   724
            return new ResponseSubscribers.HttpResponseInputStream();
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   725
        }
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   726
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   727
        /**
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   728
         * Returns a response subscriber which discards the response body. The
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   729
         * supplied value is the value that will be returned from
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   730
         * {@link HttpResponse#body()}.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   731
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   732
         * @param <U> The type of the response body
55839
d4142ab48c8a http-client-branch: minor doc formatting
dfuchs
parents: 55837
diff changeset
   733
         * @param value the value to return from HttpResponse.body(), may be {@code null}
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   734
         * @return a {@code BodySubscriber}
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   735
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   736
        public static <U> BodySubscriber<U> discard(U value) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   737
            return new ResponseSubscribers.NullSubscriber<>(Optional.ofNullable(value));
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   738
        }
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   739
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   740
        /**
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   741
         * Returns a {@code BodySubscriber} which buffers data before delivering
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   742
         * it to the given downstream subscriber. The subscriber guarantees to
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   743
         * deliver {@code buffersize} bytes of data to each invocation of the
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   744
         * downstream's {@linkplain #onNext(Object) onNext} method, except for
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   745
         * the final invocation, just before {@linkplain #onComplete() onComplete}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   746
         * is invoked. The final invocation of {@code onNext} may contain fewer
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   747
         * than {@code buffersize} bytes.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   748
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   749
         * <p> The returned subscriber delegates its {@link #getBody()} method
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   750
         * to the downstream subscriber.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   751
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   752
         * @param downstream the downstream subscriber
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   753
         * @param bufferSize the buffer size
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   754
         * @return a buffering body subscriber
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   755
         * @throws IllegalArgumentException if {@code bufferSize <= 0}
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   756
         */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   757
         public static <T> BodySubscriber<T> buffering(BodySubscriber<T> downstream,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   758
                                                       int bufferSize) {
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   759
             if (bufferSize <= 0)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   760
                 throw new IllegalArgumentException("must be greater than 0");
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   761
             return new BufferingSubscriber<T>(downstream, bufferSize);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   762
         }
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   763
    }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   764
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   765
    /**
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   766
     * A response subscriber for a HTTP/2 multi response.
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   767
     * {@Incubating}
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   768
     *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   769
     * <p> A multi response comprises a main response, and zero or more additional
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   770
     * responses. Each additional response is sent by the server in response to
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   771
     * requests (PUSH_PROMISEs) that the server also generates. Additional responses are
43302
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   772
     * typically resources that the server expects the client will need which
45de1dc92ecd 8173354: javadoc warning notice for types in Incubator Modules
chegar
parents: 42460
diff changeset
   773
     * are related to the initial request.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   774
     * <p>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   775
     * Note. Instead of implementing this interface, applications should consider
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   776
     * first using the mechanism (built on this interface) provided by
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   777
     * {@link MultiSubscriber#asMap(java.util.function.Function, boolean)
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   778
     * MultiSubscriber.asMap()} which is a slightly simplified, but also
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   779
     * general purpose interface.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   780
     * <p>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   781
     * The server generated requests are also known as <i>push promises</i>.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   782
     * The server is permitted to send any number of these requests up to the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   783
     * point where the main response is fully received. Therefore, after
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   784
     * completion of the main response, the final number of additional
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   785
     * responses is known. Additional responses may be canceled, but given that
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   786
     * the server does not wait for any acknowledgment before sending the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   787
     * response, this must be done quickly to avoid unnecessary data transmission.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   788
     *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   789
     * <p> {@code MultiSubscriber}s are parameterized with a type {@code U} which
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   790
     * represents some meaningful aggregate of the responses received. This
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   791
     * would typically be a collection of response or response body objects.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   792
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   793
     * @param <U> a type representing the aggregated results
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   794
     * @param <T> a type representing all of the response bodies
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   795
     *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   796
     * @since 9
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   797
     */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   798
    public interface MultiSubscriber<U,T> {
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   799
        /**
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   800
         * Called for the main request from the user. This {@link HttpRequest}
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   801
         * parameter is the request that was supplied to {@link
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   802
         * HttpClient#sendAsync(HttpRequest, MultiSubscriber)}. The
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   803
         * implementation must return an {@link BodyHandler} for the response
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   804
         * body.
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   805
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   806
         * @param request the request
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   807
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   808
         * @return an optional body handler
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   809
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   810
        BodyHandler<T> onRequest(HttpRequest request);
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   811
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   812
        /**
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   813
         * Called for each push promise that is received. The {@link HttpRequest}
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   814
         * parameter represents the PUSH_PROMISE. The implementation must return
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   815
         * an {@code Optional} of {@link BodyHandler} for the response body.
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   816
         * Different handlers (of the same type) can be returned for different
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   817
         * pushes within the same multi send. If no handler (an empty {@code
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   818
         * Optional}) is returned, then the push will be canceled. If required,
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   819
         * the {@code CompletableFuture<Void>} supplied to the {@code
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   820
         * onFinalPushPromise} parameter of {@link
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   821
         * #completion(CompletableFuture, CompletableFuture)} can be used to
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   822
         * determine when the final PUSH_PROMISE is received.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   823
         *
55764
34d7cc00f87a http-client-branch: WebSocket permission checks, test updates, and more
chegar
parents: 55763
diff changeset
   824
         * @param pushPromise the push promise
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   825
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   826
         * @return an optional body handler
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   827
         */
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   828
        Optional<BodyHandler<T>> onPushPromise(HttpRequest pushPromise);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   829
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   830
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   831
         * Called for each response received. For each request either one of
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   832
         * onResponse() or onError() is guaranteed to be called, but not both.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   833
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   834
         * <p> Note: The reason for switching to this callback interface rather
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   835
         * than using CompletableFutures supplied to onRequest() is that there
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   836
         * is a subtle interaction between those CFs and the CF returned from
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   837
         * completion() (or when onComplete() was called formerly). The completion()
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   838
         * CF will not complete until after all of the work done by the onResponse()
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   839
         * calls is done. Whereas if you just create CF's dependent on a supplied
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   840
         * CF (to onRequest()) then the implementation has no visibility of the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   841
         * dependent CFs and can't guarantee to call onComplete() (or complete
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   842
         * the completion() CF) after the dependent CFs complete.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   843
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   844
         * @param response the response received
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   845
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   846
        void onResponse(HttpResponse<T> response);
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   847
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   848
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   849
         * Called if an error occurs receiving a response. For each request
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   850
         * either one of onResponse() or onError() is guaranteed to be called,
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   851
         * but not both.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   852
         *
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   853
         * @param request the main request or subsequent push promise
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   854
         * @param t the Throwable that caused the error
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   855
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   856
        void onError(HttpRequest request, Throwable t);
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   857
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   858
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   859
         * Returns a {@link java.util.concurrent.CompletableFuture}{@code <U>}
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   860
         * which completes when the aggregate result object itself is available.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   861
         * It is expected that the returned {@code CompletableFuture} will depend
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   862
         * on one of the given {@code CompletableFuture<Void}s which themselves
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   863
         * complete after all individual responses associated with the multi
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   864
         * response have completed, or after all push promises have been received.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   865
         * This method is called after {@link #onRequest(HttpRequest)} but
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   866
         * before any other methods.
46052
30afc40a7f6a 8185669: Doc issues in assorted small jdk.* modules
jjg
parents: 44847
diff changeset
   867
         *
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   868
         * @implNote Implementations might follow the pattern shown below
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   869
         * <pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   870
         * {@code
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   871
         *      CompletableFuture<U> completion(
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   872
         *              CompletableFuture<Void> onComplete,
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   873
         *              CompletableFuture<Void> onFinalPushPromise)
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   874
         *      {
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   875
         *          return onComplete.thenApply((v) -> {
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   876
         *              U u = ... instantiate and populate a U instance
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   877
         *              return u;
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   878
         *          });
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   879
         *      }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   880
         * }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   881
         * </pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   882
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   883
         * @param onComplete a CompletableFuture which completes after all
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   884
         * responses have been received relating to this multi request.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   885
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   886
         * @param onFinalPushPromise CompletableFuture which completes after all
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   887
         * push promises have been received.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   888
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   889
         * @return the aggregate CF response object
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   890
         */
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   891
        CompletableFuture<U> completion(CompletableFuture<Void> onComplete,
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   892
                CompletableFuture<Void> onFinalPushPromise);
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   893
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   894
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   895
         * Returns a general purpose handler for multi responses. The aggregated
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   896
         * result object produced by this handler is a
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   897
         * {@code Map<HttpRequest,CompletableFuture<HttpResponse<V>>>}. Each
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   898
         * request (both the original user generated request and each server
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   899
         * generated push promise) is returned as a key of the map. The value
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   900
         * corresponding to each key is a
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   901
         * {@code CompletableFuture<HttpResponse<V>>}.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   902
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   903
         * <p> There are two ways to use these handlers, depending on the value
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   904
         * of the <i>completion</I> parameter. If completion is true, then the
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   905
         * aggregated result will be available after all responses have
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   906
         * themselves completed. If <i>completion</i> is false, then the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   907
         * aggregated result will be available immediately after the last push
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   908
         * promise was received. In the former case, this implies that all the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   909
         * CompletableFutures in the map values will have completed. In the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   910
         * latter case, they may or may not have completed yet.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   911
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   912
         * <p> The simplest way to use these handlers is to set completion to
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   913
         * {@code true}, and then all (results) values in the Map will be
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   914
         * accessible without blocking.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   915
         * <p>
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   916
         * See {@link #asMap(java.util.function.Function, boolean)}
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   917
         * for a code sample of using this interface.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   918
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   919
         * <p> See {@link #asMap(Function, boolean)} for a code sample of using
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   920
         * this interface.
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   921
         *
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   922
         * @param <V> the body type used for all responses
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   923
         * @param reqHandler a function invoked for the user's request and each
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   924
         *                   push promise
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   925
         * @param completion {@code true} if the aggregate CompletableFuture
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   926
         *                   completes after all responses have been received,
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   927
         *                   or {@code false} after all push promises received
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   928
         *
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   929
         * @return a MultiSubscriber
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   930
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   931
        public static <V> MultiSubscriber<MultiMapResult<V>,V> asMap(
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   932
                Function<HttpRequest, Optional<HttpResponse.BodyHandler<V>>> reqHandler,
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   933
                boolean completion) {
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   934
            return new MultiSubscriberImpl<V>(reqHandler.andThen(optv -> optv.get()),
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   935
                                              reqHandler,
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   936
                                              completion);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   937
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   938
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   939
        /**
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   940
         * Returns a general purpose handler for multi responses. This is a
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   941
         * convenience method which invokes {@link #asMap(Function,boolean)
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   942
         * asMap(Function, true)} meaning that the aggregate result
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   943
         * object completes after all responses have been received.
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   944
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   945
         * <p><b>Example usage:</b>
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   946
         * <br>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   947
         * <pre>
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   948
         * {@code
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   949
         *          HttpRequest request = HttpRequest.newBuilder()
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   950
         *                  .uri(URI.create("https://www.foo.com/"))
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   951
         *                  .GET()
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   952
         *                  .build();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   953
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   954
         *          HttpClient client = HttpClient.newHttpClient();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   955
         *
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   956
         *          Map<HttpRequest,CompletableFuture<HttpResponse<String>>> results = client
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   957
         *              .sendAsync(request, MultiSubscriber.asMap(
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   958
         *                  (req) -> Optional.of(HttpResponse.BodyHandler.asString())))
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   959
         *              .join();
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   960
         * }</pre>
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   961
         *
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   962
         * <p> The lambda in this example is the simplest possible implementation,
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   963
         * where neither the incoming requests are examined, nor the response
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   964
         * headers, and every push that the server sends is accepted. When the
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   965
         * join() call returns, all {@code HttpResponse}s and their associated
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   966
         * body objects are available.
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   967
         *
44847
cf230b81a508 8179392: Fix warnings in the httpclient javadoc
chegar
parents: 43730
diff changeset
   968
         * @param <V> the body type used for all responses
55855
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   969
         * @param reqHandler a function invoked for each push promise and the
5cb7c3fbddcd http-client-branch: review comments minor spec cleanup
chegar
parents: 55852
diff changeset
   970
         *                   main request
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   971
         * @return a MultiSubscriber
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   972
         */
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   973
        public static <V> MultiSubscriber<MultiMapResult<V>,V> asMap(
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   974
                Function<HttpRequest, Optional<HttpResponse.BodyHandler<V>>> reqHandler) {
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   975
55763
634d8e14c172 http-client-branch: intial load from jdk10/sandbox
chegar
parents: 47216
diff changeset
   976
            return asMap(reqHandler, true);
42460
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   977
        }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   978
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   979
    }
7133f144981a 8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff changeset
   980
}