author | chegar |
Thu, 08 Feb 2018 20:58:35 +0000 | |
branch | http-client-branch |
changeset 56097 | 15dc43936d39 |
parent 56092 | fd85b2bf2b0d |
child 56098 | e1890248eafe |
permissions | -rw-r--r-- |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
1 |
/* |
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
2 |
* Copyright (c) 2015, 2018, 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 |
|
56089
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56087
diff
changeset
|
26 |
package java.net.http; |
42460
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; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
29 |
import java.net.Authenticator; |
48083 | 30 |
import java.net.CookieHandler; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
31 |
import java.net.InetSocketAddress; |
48083 | 32 |
import java.net.Proxy; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
33 |
import java.net.ProxySelector; |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
34 |
import java.net.URLPermission; |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
35 |
import java.security.AccessController; |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
36 |
import java.security.PrivilegedAction; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
37 |
import java.util.Optional; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
38 |
import java.util.concurrent.CompletableFuture; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
39 |
import java.util.concurrent.Executor; |
48083 | 40 |
import java.util.concurrent.Executors; |
41 |
import java.util.concurrent.ThreadFactory; |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
42 |
import javax.net.ssl.SSLContext; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
43 |
import javax.net.ssl.SSLParameters; |
56089
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56087
diff
changeset
|
44 |
import java.net.http.HttpResponse.BodyHandler; |
42208b2f224e
http-client-branch: move to standard package and module name
chegar
parents:
56087
diff
changeset
|
45 |
import java.net.http.HttpResponse.PushPromiseHandler; |
56092
fd85b2bf2b0d
http-client-branch: move implementation to jdk.internal.net.http
chegar
parents:
56089
diff
changeset
|
46 |
import jdk.internal.net.http.HttpClientBuilderImpl; |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
47 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
48 |
/** |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
49 |
* An HTTP Client. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
50 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
51 |
* <p> An {@code HttpClient} can be used to send {@linkplain HttpRequest |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
52 |
* requests} and retrieve their {@linkplain HttpResponse responses}. An {@code |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
53 |
* HttpClient} is created through a {@link HttpClient#newBuilder() builder}. The |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
54 |
* builder can be used to configure per-client state, like: the preferred |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
55 |
* protocol version ( HTTP/1.1 or HTTP/2 ), whether to follow redirects, a |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
56 |
* proxy, an authenticator, etc. Once built, an {@code HttpClient} is immutable, |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
57 |
* and can be used to send multiple requests. |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
58 |
* |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
59 |
* <p> An {@code HttpClient} provides configuration information, and resource |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
60 |
* sharing, for all requests send through it. |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
61 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
62 |
* <p> Requests can be made either synchronously or asynchronously: |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
63 |
* <ul> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
64 |
* <li>{@link HttpClient#send(HttpRequest, BodyHandler)} blocks |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
65 |
* until the request has been sent and the response has been received.</li> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
66 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
67 |
* <li>{@link HttpClient#sendAsync(HttpRequest, BodyHandler)} sends the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
68 |
* request and receives the response asynchronously. The {@code sendAsync} |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
69 |
* method returns immediately with a {@linkplain CompletableFuture |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
70 |
* CompletableFuture}<{@linkplain HttpResponse}>. The {@code |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
71 |
* CompletableFuture} completes when the response becomes available. The |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
72 |
* returned {@code CompletableFuture} can be combined in different ways to |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
73 |
* declare dependencies among several asynchronous tasks.</li> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
74 |
* </ul> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
75 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
76 |
* <p> A {@linkplain BodyHandler BodyHandler} must be supplied for each {@code |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
77 |
* HttpRequest} sent. The {@code BodyHandler} determines how to handle the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
78 |
* response body, if any. Once an {@linkplain HttpResponse} is received, the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
79 |
* headers, response code, and body (typically) are available. Whether the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
80 |
* response body bytes has been read or not depends on the type {@code <T>} of |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
81 |
* the response body. |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
82 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
83 |
* <p><b>Synchronous Example</b> |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
84 |
* <pre>{@code HttpClient client = HttpClient.newBuilder() |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
85 |
* .version(Version.HTTP_1) |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
86 |
* .followRedirects(Redirect.SAME_PROTOCOL) |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
87 |
* .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80))) |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
88 |
* .authenticator(Authenticator.getDefault()) |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
89 |
* .build(); |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
90 |
* HttpResponse<String> response = client.send(request, BodyHandler.asString()); |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
91 |
* System.out.println(response.statusCode()); |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
92 |
* System.out.println(response.body()); }</pre> |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
93 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
94 |
* <p><b>Asynchronous Example</b> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
95 |
* <pre>{@code HttpRequest request = HttpRequest.newBuilder() |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
96 |
* .uri(URI.create("https://foo.com/")) |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
97 |
* .timeout(Duration.ofMinutes(1)) |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
98 |
* .header("Content-Type", "application/json") |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
99 |
* .POST(BodyPublisher.fromFile(Paths.get("file.json"))) |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
100 |
* .build(); |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
101 |
* client.sendAsync(request, BodyHandler.asString()) |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
102 |
* .thenApply(HttpResponse::body) |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
103 |
* .thenAccept(System.out::println) |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
104 |
* .join(); }</pre> |
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
105 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
106 |
* <p> <a id="securitychecks"></a><b>Security checks</b></a> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
107 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
108 |
* <p> If a security manager is present then security checks are performed by |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
109 |
* the HTTP Client's sending methods. An appropriate {@link URLPermission} is |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
110 |
* required to access the destination server, and proxy server if one has |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
111 |
* been configured. The form of the {@code URLPermission} required to access a |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
112 |
* proxy has a {@code method} parameter of {@code "CONNECT"} (for all kinds of |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
113 |
* proxying) and a {@code URL} string of the form {@code "socket://host:port"} |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
114 |
* where host and port specify the proxy's address. |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
115 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
116 |
* @implNote If an explicit {@linkplain HttpClient.Builder#executor(Executor) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
117 |
* executor} has not been set for an {@code HttpClient}, and a security manager |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
118 |
* has been installed, then the default executor will execute asynchronous and |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
119 |
* dependent tasks in a context that is granted no permissions. Custom |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
120 |
* {@linkplain HttpRequest.BodyPublisher request body publishers}, {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
121 |
* HttpResponse.BodyHandler response body handlers}, {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
122 |
* HttpResponse.BodySubscriber response body subscribers}, and {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
123 |
* WebSocket.Listener WebSocket Listeners}, if executing operations that require |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
124 |
* privileges, should do so within an appropriate {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
125 |
* AccessController#doPrivileged(PrivilegedAction) privileged context}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
126 |
* |
56086 | 127 |
* @since 11 |
42460
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 class HttpClient { |
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 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
132 |
* Creates an HttpClient. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
133 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
134 |
protected HttpClient() {} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
135 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
136 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
137 |
* Returns a new {@code HttpClient} with default settings. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
138 |
* |
48083 | 139 |
* <p> Equivalent to {@code newBuilder().build()}. |
140 |
* |
|
141 |
* <p> The default settings include: the "GET" request method, a preference |
|
142 |
* of {@linkplain HttpClient.Version#HTTP_2 HTTP/2}, a redirection policy of |
|
143 |
* {@linkplain Redirect#NEVER NEVER}, the {@linkplain |
|
144 |
* ProxySelector#getDefault() default proxy selector}, and the {@linkplain |
|
145 |
* SSLContext#getDefault() default SSL context}. |
|
146 |
* |
|
147 |
* @implNote The system-wide default values are retrieved at the time the |
|
148 |
* {@code HttpClient} instance is constructed. Changing the system-wide |
|
149 |
* values after an {@code HttpClient} instance has been built, for |
|
150 |
* instance, by calling {@link ProxySelector#setDefault(ProxySelector)} |
|
151 |
* or {@link SSLContext#setDefault(SSLContext)}, has no effect on already |
|
152 |
* built instances. |
|
153 |
* |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
154 |
* @return a new HttpClient |
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 |
public static HttpClient newHttpClient() { |
48083 | 157 |
return newBuilder().build(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
158 |
} |
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 |
* Creates a new {@code HttpClient} builder. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
162 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
163 |
* @return an {@code HttpClient.Builder} |
42460
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 static Builder newBuilder() { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
166 |
return new HttpClientBuilderImpl(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
167 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
168 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
169 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
170 |
* A builder of {@link HttpClient}s. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
171 |
* |
48083 | 172 |
* <p> Builders are created by invoking {@linkplain HttpClient#newBuilder() |
173 |
* newBuilder}. Each of the setter methods modifies the state of the builder |
|
174 |
* and returns the same instance. Builders are not thread-safe and should not be |
|
175 |
* used concurrently from multiple threads without external synchronization. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
176 |
* |
56086 | 177 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
178 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
179 |
public abstract static class Builder { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
180 |
|
48083 | 181 |
/** |
182 |
* A proxy selector that always return {@link Proxy#NO_PROXY} implying |
|
183 |
* a direct connection. |
|
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
184 |
* |
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
185 |
* <p> This is a convenience object that can be passed to |
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
186 |
* {@link #proxy(ProxySelector)} in order to build an instance of |
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
187 |
* {@link HttpClient} that uses no proxy. |
48083 | 188 |
*/ |
189 |
public static final ProxySelector NO_PROXY = ProxySelector.of(null); |
|
190 |
||
191 |
/** |
|
192 |
* Creates a Builder. |
|
193 |
*/ |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
194 |
protected Builder() {} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
195 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
196 |
/** |
48083 | 197 |
* Sets a cookie handler. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
198 |
* |
48083 | 199 |
* @param cookieHandler the cookie handler |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
200 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
201 |
*/ |
48083 | 202 |
public abstract Builder cookieHandler(CookieHandler cookieHandler); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
203 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
204 |
/** |
48083 | 205 |
* Sets an {@code SSLContext}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
206 |
* |
48083 | 207 |
* <p> If this method is not invoked prior to {@linkplain #build() |
208 |
* building}, then newly built clients will use the {@linkplain |
|
209 |
* SSLContext#getDefault() default context}, which is normally adequate |
|
210 |
* for client applications that do not need to specify protocols, or |
|
211 |
* require client authentication. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
212 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
213 |
* @param sslContext the SSLContext |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
214 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
215 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
216 |
public abstract Builder sslContext(SSLContext sslContext); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
217 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
218 |
/** |
48083 | 219 |
* Sets an {@code SSLParameters}. |
220 |
* |
|
221 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
222 |
* building}, then newly built clients will use a default, |
|
223 |
* implementation specific, set of parameters. |
|
224 |
* |
|
225 |
* <p> Some parameters which are used internally by the HTTP Client |
|
226 |
* implementation (such as the application protocol list) should not be |
|
227 |
* set by callers, as they may be ignored. The contents of the given |
|
228 |
* object are copied. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
229 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
230 |
* @param sslParameters the SSLParameters |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
231 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
232 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
233 |
public abstract Builder sslParameters(SSLParameters sslParameters); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
234 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
235 |
/** |
48083 | 236 |
* Sets the executor to be used for asynchronous and dependent tasks. |
237 |
* |
|
238 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
239 |
* building}, a default executor is created for each newly built {@code |
|
240 |
* HttpClient}. The default executor uses a {@linkplain |
|
241 |
* Executors#newCachedThreadPool(ThreadFactory) cached thread pool}, |
|
242 |
* with a custom thread factory. |
|
243 |
* |
|
244 |
* @implNote If a security manager has been installed, the thread |
|
245 |
* factory creates threads that run with an access control context that |
|
246 |
* has no permissions. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
247 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
248 |
* @param executor the Executor |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
249 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
250 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
251 |
public abstract Builder executor(Executor executor); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
252 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
253 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
254 |
* Specifies whether requests will automatically follow redirects issued |
48083 | 255 |
* by the server. |
256 |
* |
|
257 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
258 |
* building}, then newly built clients will use a default redirection |
|
259 |
* policy of {@link Redirect#NEVER NEVER}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
260 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
261 |
* @param policy the redirection policy |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
262 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
263 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
264 |
public abstract Builder followRedirects(Redirect policy); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
265 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
266 |
/** |
48083 | 267 |
* Requests a specific HTTP protocol version where possible. |
268 |
* |
|
269 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
270 |
* building}, then newly built clients will prefer {@linkplain |
|
271 |
* Version#HTTP_2 HTTP/2}. |
|
272 |
* |
|
273 |
* <p> If set to {@linkplain Version#HTTP_2 HTTP/2}, then each request |
|
274 |
* will attempt to upgrade to HTTP/2. If the upgrade succeeds, then the |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
275 |
* response to this request will use HTTP/2 and all subsequent requests |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
276 |
* and responses to the same |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
277 |
* <a href="https://tools.ietf.org/html/rfc6454#section-4">origin server</a> |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
278 |
* will use HTTP/2. If the upgrade fails, then the response will be |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
279 |
* handled using HTTP/1.1 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
280 |
* |
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
281 |
* @implNote Constraints may also affect the selection of protocol version. |
56043
08e8e41841cf
http-client-branch: changed default protocol version when plain http over proxy requested.
michaelm
parents:
56025
diff
changeset
|
282 |
* For example, if HTTP/2 is requested through a proxy, and if the implementation |
08e8e41841cf
http-client-branch: changed default protocol version when plain http over proxy requested.
michaelm
parents:
56025
diff
changeset
|
283 |
* does not support this mode, then HTTP/1.1 may be used |
08e8e41841cf
http-client-branch: changed default protocol version when plain http over proxy requested.
michaelm
parents:
56025
diff
changeset
|
284 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
285 |
* @param version the requested HTTP protocol version |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
286 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
287 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
288 |
public abstract Builder version(HttpClient.Version version); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
289 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
290 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
291 |
* Sets the default priority for any HTTP/2 requests sent from this |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
292 |
* client. The value provided must be between {@code 1} and {@code 256} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
293 |
* (inclusive). |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
294 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
295 |
* @param priority the priority weighting |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
296 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
297 |
* @throws IllegalArgumentException if the given priority is out of range |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
298 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
299 |
public abstract Builder priority(int priority); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
300 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
301 |
/** |
48083 | 302 |
* Sets a {@link java.net.ProxySelector}. |
303 |
* |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
304 |
* @apiNote {@link ProxySelector#of(InetSocketAddress) ProxySelector::of} |
48083 | 305 |
* provides a {@code ProxySelector} which uses a single proxy for all |
306 |
* requests. The system-wide proxy selector can be retrieved by |
|
307 |
* {@link ProxySelector#getDefault()}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
308 |
* |
48083 | 309 |
* @implNote |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
310 |
* If this method is not invoked prior to {@linkplain #build() building}, |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
311 |
* then newly built clients will use the {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
312 |
* ProxySelector#getDefault() default proxy selector}, which is usually |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
313 |
* adequate for client applications. This default behavior can be turned |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
314 |
* off by supplying an explicit proxy selector to this method, such as |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
315 |
* {@link #NO_PROXY} or one returned by {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
316 |
* ProxySelector#of(InetSocketAddress) ProxySelector::of}, before |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
317 |
* {@linkplain #build() building}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
318 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
319 |
* @param selector the ProxySelector |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
320 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
321 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
322 |
public abstract Builder proxy(ProxySelector selector); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
323 |
|
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 |
* Sets an authenticator to use for HTTP authentication. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
326 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
327 |
* @param a the Authenticator |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
328 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
329 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
330 |
public abstract Builder authenticator(Authenticator a); |
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 |
/** |
48083 | 333 |
* Returns a new {@link HttpClient} built from the current state of this |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
334 |
* builder. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
335 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
336 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
337 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
338 |
public abstract HttpClient build(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
339 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
340 |
|
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 |
/** |
48083 | 343 |
* Returns an {@code Optional} containing this client's {@linkplain |
344 |
* CookieHandler}. If no {@code CookieHandler} was set in this client's |
|
345 |
* builder, then the {@code Optional} is empty. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
346 |
* |
48083 | 347 |
* @return an {@code Optional} containing this client's {@code CookieHandler} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
348 |
*/ |
48083 | 349 |
public abstract Optional<CookieHandler> cookieHandler(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
350 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
351 |
/** |
48083 | 352 |
* Returns the follow redirects policy for this client. The default value |
353 |
* for client's built by builders that do not specify a redirect policy is |
|
354 |
* {@link HttpClient.Redirect#NEVER NEVER}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
355 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
356 |
* @return this client's follow redirects setting |
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 abstract Redirect followRedirects(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
359 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
360 |
/** |
48083 | 361 |
* Returns an {@code Optional} containing the {@code ProxySelector} |
362 |
* supplied to this client. If no proxy selector was set in this client's |
|
363 |
* builder, then the {@code Optional} is empty. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
364 |
* |
48083 | 365 |
* <p> Even though this method may return an empty optional, the {@code |
366 |
* HttpClient} may still have an non-exposed {@linkplain |
|
367 |
* Builder#proxy(ProxySelector) default proxy selector} that is |
|
368 |
* used for sending HTTP requests. |
|
369 |
* |
|
370 |
* @return an {@code Optional} containing the proxy selector supplied |
|
371 |
* to this client. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
372 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
373 |
public abstract Optional<ProxySelector> proxy(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
374 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
375 |
/** |
48083 | 376 |
* Returns this client's {@code SSLContext}. |
377 |
* |
|
378 |
* <p> If no {@code SSLContext} was set in this client's builder, then the |
|
379 |
* {@linkplain SSLContext#getDefault() default context} is returned. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
380 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
381 |
* @return this client's SSLContext |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
382 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
383 |
public abstract SSLContext sslContext(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
384 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
385 |
/** |
48083 | 386 |
* Returns a copy of this client's {@link SSLParameters}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
387 |
* |
48083 | 388 |
* <p> If no {@code SSLParameters} were set in the client's builder, then an |
389 |
* implementation specific default set of parameters, that the client will |
|
390 |
* use, is returned. |
|
391 |
* |
|
392 |
* @return this client's {@code SSLParameters} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
393 |
*/ |
48083 | 394 |
public abstract SSLParameters sslParameters(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
395 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
396 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
397 |
* Returns an {@code Optional} containing the {@link Authenticator} set on |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
398 |
* this client. If no {@code Authenticator} was set in the client's builder, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
399 |
* then the {@code Optional} is empty. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
400 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
401 |
* @return an {@code Optional} containing this client's {@code Authenticator} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
402 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
403 |
public abstract Optional<Authenticator> authenticator(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
404 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
405 |
/** |
56043
08e8e41841cf
http-client-branch: changed default protocol version when plain http over proxy requested.
michaelm
parents:
56025
diff
changeset
|
406 |
* Returns the preferred HTTP protocol version for this client. The default |
44854
5a486e0acd29
8175814: Update default HttpClient protocol version and optional request version
michaelm
parents:
43302
diff
changeset
|
407 |
* value is {@link HttpClient.Version#HTTP_2} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
408 |
* |
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
409 |
* @implNote Constraints may also affect the selection of protocol version. |
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
410 |
* For example, if HTTP/2 is requested through a proxy, and if the |
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
411 |
* implementation does not support this mode, then HTTP/1.1 may be used |
56043
08e8e41841cf
http-client-branch: changed default protocol version when plain http over proxy requested.
michaelm
parents:
56025
diff
changeset
|
412 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
413 |
* @return the HTTP protocol version requested |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
414 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
415 |
public abstract HttpClient.Version version(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
416 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
417 |
/** |
48083 | 418 |
* Returns an {@code Optional} containing this client's {@linkplain |
419 |
* Executor}. If no {@code Executor} was set in the client's builder, |
|
420 |
* then the {@code Optional} is empty. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
421 |
* |
48083 | 422 |
* <p> Even though this method may return an empty optional, the {@code |
423 |
* HttpClient} may still have an non-exposed {@linkplain |
|
424 |
* HttpClient.Builder#executor(Executor) default executor} that is used for |
|
425 |
* executing asynchronous and dependent tasks. |
|
426 |
* |
|
427 |
* @return an {@code Optional} containing this client's {@code Executor} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
428 |
*/ |
48083 | 429 |
public abstract Optional<Executor> executor(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
430 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
431 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
432 |
* The HTTP protocol version. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
433 |
* |
56086 | 434 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
435 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
436 |
public enum Version { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
437 |
|
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 |
* HTTP version 1.1 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
440 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
441 |
HTTP_1_1, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
442 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
443 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
444 |
* HTTP version 2 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
445 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
446 |
HTTP_2 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
447 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
448 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
449 |
/** |
43302
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
450 |
* Defines automatic redirection policy. |
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
451 |
* |
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
452 |
* <p> This is checked whenever a {@code 3XX} response code is received. If |
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
453 |
* redirection does not happen automatically then the response is returned |
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
454 |
* to the user, where it can be handled manually. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
455 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
456 |
* <p> {@code Redirect} policy is set via the {@link |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
457 |
* HttpClient.Builder#followRedirects(HttpClient.Redirect)} method. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
458 |
* |
56086 | 459 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
460 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
461 |
public enum Redirect { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
462 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
463 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
464 |
* Never redirect. |
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 |
NEVER, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
467 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
468 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
469 |
* Always redirect. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
470 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
471 |
ALWAYS, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
472 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
473 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
474 |
* Redirect to same protocol only. Redirection may occur from HTTP URLs |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
475 |
* to other HTTP URLs, and from HTTPS URLs to other HTTPS URLs. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
476 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
477 |
SAME_PROTOCOL, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
478 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
479 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
480 |
* Redirect always except from HTTPS URLs to HTTP URLs. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
481 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
482 |
SECURE |
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 |
/** |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
486 |
* Sends the given request using this client, blocking if necessary to get |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
487 |
* the response. The returned {@link HttpResponse}{@code <T>} contains the |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
488 |
* response status, headers, and body ( as handled by given response body |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
489 |
* handler ). |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
490 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
491 |
* @param <T> the response body type |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
492 |
* @param request the request |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
493 |
* @param responseBodyHandler the response body handler |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
494 |
* @return the response |
48083 | 495 |
* @throws IOException if an I/O error occurs when sending or receiving |
496 |
* @throws InterruptedException if the operation is interrupted |
|
497 |
* @throws IllegalArgumentException if the request method is not supported |
|
498 |
* @throws SecurityException If a security manager has been installed |
|
499 |
* and it denies {@link java.net.URLPermission access} to the |
|
500 |
* URL in the given request, or proxy if one is configured. |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
501 |
* See <a href="#securitychecks">security checks</a> for further |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
502 |
* information. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
503 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
504 |
public abstract <T> HttpResponse<T> |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
505 |
send(HttpRequest request, HttpResponse.BodyHandler<T> responseBodyHandler) |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
506 |
throws IOException, InterruptedException; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
507 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
508 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
509 |
* Sends the given request asynchronously using this client with the given |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
510 |
* response body handler. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
511 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
512 |
* <p> Equivalent to: {@code sendAsync(request, responseBodyHandler, null)}. |
56025 | 513 |
* |
514 |
* @param <T> the response body type |
|
515 |
* @param request the request |
|
516 |
* @param responseBodyHandler the response body handler |
|
517 |
* @return a {@code CompletableFuture<HttpResponse<T>>} |
|
518 |
*/ |
|
519 |
public abstract <T> CompletableFuture<HttpResponse<T>> |
|
520 |
sendAsync(HttpRequest request, |
|
521 |
BodyHandler<T> responseBodyHandler); |
|
522 |
||
523 |
/** |
|
524 |
* Sends the given request asynchronously using this client with the given |
|
525 |
* response body handler and push promise handler. |
|
526 |
* |
|
527 |
* <p> The returned completable future, if completed successfully, completes |
|
528 |
* with an {@link HttpResponse}{@code <T>} that contains the response status, |
|
529 |
* headers, and body ( as handled by given response body handler ). |
|
530 |
* |
|
531 |
* <p> {@linkplain PushPromiseHandler Push promises} received, if any, are |
|
532 |
* handled by the given {@code pushPromiseHandler}. A {@code null} valued |
|
533 |
* {@code pushPromiseHandler} rejects any push promises. |
|
534 |
* |
|
48083 | 535 |
* <p> The returned completable future completes exceptionally with: |
536 |
* <ul> |
|
537 |
* <li>{@link IOException} - if an I/O error occurs when sending or receiving</li> |
|
538 |
* <li>{@link IllegalArgumentException} - if the request method is not supported</li> |
|
539 |
* <li>{@link SecurityException} - If a security manager has been installed |
|
540 |
* and it denies {@link java.net.URLPermission access} to the |
|
541 |
* URL in the given request, or proxy if one is configured. |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
542 |
* See <a href="#securitychecks">security checks</a> for further |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
543 |
* information.</li> |
48083 | 544 |
* </ul> |
545 |
* |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
546 |
* @param <T> the response body type |
56025 | 547 |
* @param request the request |
56010 | 548 |
* @param responseBodyHandler the response body handler |
549 |
* @param pushPromiseHandler push promise handler, may be null |
|
550 |
* @return a {@code CompletableFuture<HttpResponse<T>>} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
551 |
*/ |
56010 | 552 |
public abstract <T> CompletableFuture<HttpResponse<T>> |
56025 | 553 |
sendAsync(HttpRequest request, |
56010 | 554 |
BodyHandler<T> responseBodyHandler, |
555 |
PushPromiseHandler<T> pushPromiseHandler); |
|
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 |
/** |
48083 | 558 |
* Creates a new {@code WebSocket} builder (optional operation). |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
559 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
560 |
* <p> <b>Example</b> |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
561 |
* <pre>{@code HttpClient client = HttpClient.newHttpClient(); |
48083 | 562 |
* CompletableFuture<WebSocket> ws = client.newWebSocketBuilder() |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
563 |
* .buildAsync(URI.create("ws://websocket.example.com"), listener); }</pre> |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
564 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
565 |
* <p> Finer control over the WebSocket Opening Handshake can be achieved |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
566 |
* by using a custom {@code HttpClient}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
567 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
568 |
* <p> <b>Example</b> |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
569 |
* <pre>{@code InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
570 |
* HttpClient client = HttpClient.newBuilder() |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
571 |
* .proxy(ProxySelector.of(addr)) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
572 |
* .build(); |
48083 | 573 |
* CompletableFuture<WebSocket> ws = client.newWebSocketBuilder() |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
574 |
* .buildAsync(URI.create("ws://websocket.example.com"), listener); }</pre> |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
575 |
* |
48083 | 576 |
* <p> A {@code WebSocket.Builder} returned from this method is not safe for |
577 |
* use by multiple threads without external synchronization. |
|
578 |
* |
|
579 |
* @implSpec The default implementation of this method throws |
|
580 |
* {@code UnsupportedOperationException}. Clients obtained through |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
581 |
* {@link HttpClient#newHttpClient()} or {@link HttpClient#newBuilder()} |
48083 | 582 |
* return a {@code WebSocket} builder. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
583 |
* |
48083 | 584 |
* @implNote Both builder and {@code WebSocket}s created with it operate in |
585 |
* a non-blocking fashion. That is, their methods do not block before |
|
586 |
* returning a {@code CompletableFuture}. Asynchronous tasks are executed in |
|
587 |
* this {@code HttpClient}'s executor. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
588 |
* |
48083 | 589 |
* <p> When a {@code CompletionStage} returned from |
590 |
* {@link WebSocket.Listener#onClose Listener.onClose} completes, |
|
591 |
* the {@code WebSocket} will send a Close message that has the same code |
|
592 |
* the received message has and an empty reason. |
|
593 |
* |
|
594 |
* @return a {@code WebSocket.Builder} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
595 |
* @throws UnsupportedOperationException |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
596 |
* if this {@code HttpClient} does not provide WebSocket support |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
597 |
*/ |
48083 | 598 |
public WebSocket.Builder newWebSocketBuilder() { |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
599 |
throw new UnsupportedOperationException(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
600 |
} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
601 |
} |