author | chegar |
Fri, 09 Feb 2018 12:34:07 +0000 | |
branch | http-client-branch |
changeset 56099 | 41ba54ac9403 |
parent 56098 | e1890248eafe |
child 56140 | 049b6940e9db |
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 |
* |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
62 |
* <p> A {@link BodyHandler BodyHandler} must be supplied for each {@link |
56098 | 63 |
* HttpRequest} sent. The {@code BodyHandler} determines how to handle the |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
64 |
* response body, if any. Once an {@link HttpResponse} is received, the |
56098 | 65 |
* headers, response code, and body (typically) are available. Whether the |
66 |
* response body bytes has been read or not depends on the type {@code <T>} of |
|
67 |
* the response body. |
|
68 |
* |
|
69 |
* <p> Requests can be sent either synchronously or asynchronously: |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
70 |
* <ul> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
71 |
* <li>{@link HttpClient#send(HttpRequest, BodyHandler)} blocks |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
72 |
* 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
|
73 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
74 |
* <li>{@link HttpClient#sendAsync(HttpRequest, BodyHandler)} sends the |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
75 |
* request and receives the response asynchronously. The {@code sendAsync} |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
76 |
* method returns immediately with a {@link CompletableFuture |
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
77 |
* CompletableFuture}<{@link HttpResponse}>. The {@code |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
78 |
* CompletableFuture} completes when the response becomes available. The |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
79 |
* returned {@code CompletableFuture} can be combined in different ways to |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
80 |
* declare dependencies among several asynchronous tasks.</li> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
81 |
* </ul> |
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) |
56098 | 103 |
* .thenAccept(System.out::println); }</pre> |
56085
544869ae0b16
http-client-branch: remove remaining vestiges of MultiSubscriber and minor doc cleanup
chegar
parents:
56079
diff
changeset
|
104 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
105 |
* <p> <a id="securitychecks"></a><b>Security checks</b></a> |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
106 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
107 |
* <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
|
108 |
* 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
|
109 |
* 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
|
110 |
* 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
|
111 |
* 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
|
112 |
* 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
|
113 |
* where host and port specify the proxy's address. |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
114 |
* |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
115 |
* @implNote If an explicit {@linkplain HttpClient.Builder#executor(Executor) |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
116 |
* 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
|
117 |
* 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
|
118 |
* 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
|
119 |
* {@linkplain HttpRequest.BodyPublisher request body publishers}, {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
120 |
* HttpResponse.BodyHandler response body handlers}, {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
121 |
* HttpResponse.BodySubscriber response body subscribers}, and {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
122 |
* WebSocket.Listener WebSocket Listeners}, if executing operations that require |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
123 |
* privileges, should do so within an appropriate {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
124 |
* AccessController#doPrivileged(PrivilegedAction) privileged context}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
125 |
* |
56086 | 126 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
127 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
128 |
public abstract class HttpClient { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
129 |
|
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 |
* Creates an HttpClient. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
132 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
133 |
protected HttpClient() {} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
134 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
135 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
136 |
* 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
|
137 |
* |
48083 | 138 |
* <p> Equivalent to {@code newBuilder().build()}. |
139 |
* |
|
140 |
* <p> The default settings include: the "GET" request method, a preference |
|
141 |
* of {@linkplain HttpClient.Version#HTTP_2 HTTP/2}, a redirection policy of |
|
142 |
* {@linkplain Redirect#NEVER NEVER}, the {@linkplain |
|
143 |
* ProxySelector#getDefault() default proxy selector}, and the {@linkplain |
|
144 |
* SSLContext#getDefault() default SSL context}. |
|
145 |
* |
|
146 |
* @implNote The system-wide default values are retrieved at the time the |
|
147 |
* {@code HttpClient} instance is constructed. Changing the system-wide |
|
148 |
* values after an {@code HttpClient} instance has been built, for |
|
149 |
* instance, by calling {@link ProxySelector#setDefault(ProxySelector)} |
|
150 |
* or {@link SSLContext#setDefault(SSLContext)}, has no effect on already |
|
151 |
* built instances. |
|
152 |
* |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
153 |
* @return a new HttpClient |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
154 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
155 |
public static HttpClient newHttpClient() { |
48083 | 156 |
return newBuilder().build(); |
42460
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 |
|
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 |
* Creates a new {@code HttpClient} builder. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
161 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
162 |
* @return an {@code HttpClient.Builder} |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
163 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
164 |
public static Builder newBuilder() { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
165 |
return new HttpClientBuilderImpl(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
166 |
} |
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 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
169 |
* 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
|
170 |
* |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
171 |
* <p> Builders are created by invoking {@link HttpClient#newBuilder() |
48083 | 172 |
* newBuilder}. Each of the setter methods modifies the state of the builder |
173 |
* and returns the same instance. Builders are not thread-safe and should not be |
|
174 |
* 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
|
175 |
* |
56086 | 176 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
177 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
178 |
public abstract static class Builder { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
179 |
|
48083 | 180 |
/** |
181 |
* A proxy selector that always return {@link Proxy#NO_PROXY} implying |
|
182 |
* a direct connection. |
|
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
183 |
* |
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
184 |
* <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
|
185 |
* {@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
|
186 |
* {@link HttpClient} that uses no proxy. |
48083 | 187 |
*/ |
188 |
public static final ProxySelector NO_PROXY = ProxySelector.of(null); |
|
189 |
||
190 |
/** |
|
191 |
* Creates a Builder. |
|
192 |
*/ |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
193 |
protected Builder() {} |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
194 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
195 |
/** |
48083 | 196 |
* Sets a cookie handler. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
197 |
* |
48083 | 198 |
* @param cookieHandler the cookie handler |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
199 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
200 |
*/ |
48083 | 201 |
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
|
202 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
203 |
/** |
48083 | 204 |
* Sets an {@code SSLContext}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
205 |
* |
48083 | 206 |
* <p> If this method is not invoked prior to {@linkplain #build() |
207 |
* building}, then newly built clients will use the {@linkplain |
|
208 |
* SSLContext#getDefault() default context}, which is normally adequate |
|
209 |
* for client applications that do not need to specify protocols, or |
|
210 |
* require client authentication. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
211 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
212 |
* @param sslContext the SSLContext |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
213 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
214 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
215 |
public abstract Builder sslContext(SSLContext sslContext); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
216 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
217 |
/** |
48083 | 218 |
* Sets an {@code SSLParameters}. |
219 |
* |
|
220 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
221 |
* building}, then newly built clients will use a default, |
|
222 |
* implementation specific, set of parameters. |
|
223 |
* |
|
224 |
* <p> Some parameters which are used internally by the HTTP Client |
|
225 |
* implementation (such as the application protocol list) should not be |
|
226 |
* set by callers, as they may be ignored. The contents of the given |
|
227 |
* object are copied. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
228 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
229 |
* @param sslParameters the SSLParameters |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
230 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
231 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
232 |
public abstract Builder sslParameters(SSLParameters sslParameters); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
233 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
234 |
/** |
48083 | 235 |
* Sets the executor to be used for asynchronous and dependent tasks. |
236 |
* |
|
237 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
238 |
* building}, a default executor is created for each newly built {@code |
|
239 |
* HttpClient}. The default executor uses a {@linkplain |
|
240 |
* Executors#newCachedThreadPool(ThreadFactory) cached thread pool}, |
|
241 |
* with a custom thread factory. |
|
242 |
* |
|
243 |
* @implNote If a security manager has been installed, the thread |
|
244 |
* factory creates threads that run with an access control context that |
|
245 |
* has no permissions. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
246 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
247 |
* @param executor the Executor |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
248 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
249 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
250 |
public abstract Builder executor(Executor executor); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
251 |
|
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 |
* Specifies whether requests will automatically follow redirects issued |
48083 | 254 |
* by the server. |
255 |
* |
|
256 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
257 |
* building}, then newly built clients will use a default redirection |
|
258 |
* 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
|
259 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
260 |
* @param policy the redirection policy |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
261 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
262 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
263 |
public abstract Builder followRedirects(Redirect policy); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
264 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
265 |
/** |
48083 | 266 |
* Requests a specific HTTP protocol version where possible. |
267 |
* |
|
268 |
* <p> If this method is not invoked prior to {@linkplain #build() |
|
269 |
* building}, then newly built clients will prefer {@linkplain |
|
270 |
* Version#HTTP_2 HTTP/2}. |
|
271 |
* |
|
272 |
* <p> If set to {@linkplain Version#HTTP_2 HTTP/2}, then each request |
|
273 |
* 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
|
274 |
* 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
|
275 |
* and responses to the same |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
276 |
* <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
|
277 |
* 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
|
278 |
* handled using HTTP/1.1 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
279 |
* |
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
280 |
* @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
|
281 |
* 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
|
282 |
* 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
|
283 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
284 |
* @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
|
285 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
286 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
287 |
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
|
288 |
|
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 |
* 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
|
291 |
* 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
|
292 |
* (inclusive). |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
293 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
294 |
* @param priority the priority weighting |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
295 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
296 |
* @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
|
297 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
298 |
public abstract Builder priority(int priority); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
299 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
300 |
/** |
48083 | 301 |
* Sets a {@link java.net.ProxySelector}. |
302 |
* |
|
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
303 |
* @apiNote {@link ProxySelector#of(InetSocketAddress) ProxySelector::of} |
48083 | 304 |
* provides a {@code ProxySelector} which uses a single proxy for all |
305 |
* requests. The system-wide proxy selector can be retrieved by |
|
306 |
* {@link ProxySelector#getDefault()}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
307 |
* |
48083 | 308 |
* @implNote |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
309 |
* 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
|
310 |
* then newly built clients will use the {@linkplain |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
311 |
* ProxySelector#getDefault() default proxy selector}, which is usually |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
312 |
* adequate for client applications. This default behavior can be turned |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
313 |
* off by supplying an explicit proxy selector to this method, such as |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
314 |
* {@link #NO_PROXY} or one returned by {@link |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
315 |
* ProxySelector#of(InetSocketAddress) ProxySelector::of}, before |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
316 |
* {@linkplain #build() building}. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
317 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
318 |
* @param selector the ProxySelector |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
319 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
320 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
321 |
public abstract Builder proxy(ProxySelector selector); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
322 |
|
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 |
* 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
|
325 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
326 |
* @param a the Authenticator |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
327 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
328 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
329 |
public abstract Builder authenticator(Authenticator a); |
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 |
/** |
48083 | 332 |
* 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
|
333 |
* builder. |
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 |
* @return this builder |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
336 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
337 |
public abstract HttpClient build(); |
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 |
|
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 |
/** |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
342 |
* Returns an {@code Optional} containing this client's {@link |
48083 | 343 |
* CookieHandler}. If no {@code CookieHandler} was set in this client's |
344 |
* 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
|
345 |
* |
48083 | 346 |
* @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
|
347 |
*/ |
48083 | 348 |
public abstract Optional<CookieHandler> cookieHandler(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
349 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
350 |
/** |
48083 | 351 |
* Returns the follow redirects policy for this client. The default value |
352 |
* for client's built by builders that do not specify a redirect policy is |
|
353 |
* {@link HttpClient.Redirect#NEVER NEVER}. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
354 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
355 |
* @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
|
356 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
357 |
public abstract Redirect followRedirects(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
358 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
359 |
/** |
48083 | 360 |
* Returns an {@code Optional} containing the {@code ProxySelector} |
361 |
* supplied to this client. If no proxy selector was set in this client's |
|
362 |
* 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
|
363 |
* |
48083 | 364 |
* <p> Even though this method may return an empty optional, the {@code |
365 |
* HttpClient} may still have an non-exposed {@linkplain |
|
366 |
* Builder#proxy(ProxySelector) default proxy selector} that is |
|
367 |
* used for sending HTTP requests. |
|
368 |
* |
|
369 |
* @return an {@code Optional} containing the proxy selector supplied |
|
370 |
* to this client. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
371 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
372 |
public abstract Optional<ProxySelector> proxy(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
373 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
374 |
/** |
48083 | 375 |
* Returns this client's {@code SSLContext}. |
376 |
* |
|
377 |
* <p> If no {@code SSLContext} was set in this client's builder, then the |
|
378 |
* {@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
|
379 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
380 |
* @return this client's SSLContext |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
381 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
382 |
public abstract SSLContext sslContext(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
383 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
384 |
/** |
48083 | 385 |
* 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
|
386 |
* |
48083 | 387 |
* <p> If no {@code SSLParameters} were set in the client's builder, then an |
388 |
* implementation specific default set of parameters, that the client will |
|
389 |
* use, is returned. |
|
390 |
* |
|
391 |
* @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
|
392 |
*/ |
48083 | 393 |
public abstract SSLParameters sslParameters(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
394 |
|
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 |
* 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
|
397 |
* 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
|
398 |
* then the {@code Optional} is empty. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
399 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
400 |
* @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
|
401 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
402 |
public abstract Optional<Authenticator> authenticator(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
403 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
404 |
/** |
56043
08e8e41841cf
http-client-branch: changed default protocol version when plain http over proxy requested.
michaelm
parents:
56025
diff
changeset
|
405 |
* 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
|
406 |
* 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
|
407 |
* |
56079
d23b02f37fce
http-client-branch: more remaining impl types to internal
chegar
parents:
56043
diff
changeset
|
408 |
* @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
|
409 |
* 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
|
410 |
* 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
|
411 |
* |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
412 |
* @return the HTTP protocol version requested |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
413 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
414 |
public abstract HttpClient.Version version(); |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
415 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
416 |
/** |
56099
41ba54ac9403
http-client-branch: revert overzealous use of @linkplain
chegar
parents:
56098
diff
changeset
|
417 |
* Returns an {@code Optional} containing this client's {@link |
48083 | 418 |
* Executor}. If no {@code Executor} was set in the client's builder, |
419 |
* 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
|
420 |
* |
48083 | 421 |
* <p> Even though this method may return an empty optional, the {@code |
422 |
* HttpClient} may still have an non-exposed {@linkplain |
|
423 |
* HttpClient.Builder#executor(Executor) default executor} that is used for |
|
424 |
* executing asynchronous and dependent tasks. |
|
425 |
* |
|
426 |
* @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
|
427 |
*/ |
48083 | 428 |
public abstract Optional<Executor> executor(); |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
429 |
|
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 |
* The HTTP protocol version. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
432 |
* |
56086 | 433 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
434 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
435 |
public enum Version { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
436 |
|
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 |
* HTTP version 1.1 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
439 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
440 |
HTTP_1_1, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
441 |
|
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 |
* HTTP version 2 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
444 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
445 |
HTTP_2 |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
446 |
} |
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 |
/** |
43302
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
449 |
* Defines automatic redirection policy. |
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
450 |
* |
45de1dc92ecd
8173354: javadoc warning notice for types in Incubator Modules
chegar
parents:
42460
diff
changeset
|
451 |
* <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
|
452 |
* 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
|
453 |
* 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
|
454 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
455 |
* <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
|
456 |
* HttpClient.Builder#followRedirects(HttpClient.Redirect)} method. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
457 |
* |
56086 | 458 |
* @since 11 |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
459 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
460 |
public enum Redirect { |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
461 |
|
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 |
* Never redirect. |
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 |
NEVER, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
466 |
|
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 |
* Always redirect. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
469 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
470 |
ALWAYS, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
471 |
|
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 |
* 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
|
474 |
* 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
|
475 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
476 |
SAME_PROTOCOL, |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
477 |
|
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 |
* 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
|
480 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
481 |
SECURE |
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 |
* 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
|
486 |
* 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
|
487 |
* 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
|
488 |
* handler ). |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
489 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
490 |
* @param <T> the response body type |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
491 |
* @param request the request |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
492 |
* @param responseBodyHandler the response body handler |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
493 |
* @return the response |
48083 | 494 |
* @throws IOException if an I/O error occurs when sending or receiving |
495 |
* @throws InterruptedException if the operation is interrupted |
|
496 |
* @throws IllegalArgumentException if the request method is not supported |
|
497 |
* @throws SecurityException If a security manager has been installed |
|
498 |
* and it denies {@link java.net.URLPermission access} to the |
|
499 |
* 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
|
500 |
* See <a href="#securitychecks">security checks</a> for further |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
501 |
* information. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
502 |
*/ |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
503 |
public abstract <T> HttpResponse<T> |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
504 |
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
|
505 |
throws IOException, InterruptedException; |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
506 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
507 |
/** |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
508 |
* 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
|
509 |
* response body handler. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
510 |
* |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
511 |
* <p> Equivalent to: {@code sendAsync(request, responseBodyHandler, null)}. |
56025 | 512 |
* |
513 |
* @param <T> the response body type |
|
514 |
* @param request the request |
|
515 |
* @param responseBodyHandler the response body handler |
|
516 |
* @return a {@code CompletableFuture<HttpResponse<T>>} |
|
517 |
*/ |
|
518 |
public abstract <T> CompletableFuture<HttpResponse<T>> |
|
519 |
sendAsync(HttpRequest request, |
|
520 |
BodyHandler<T> responseBodyHandler); |
|
521 |
||
522 |
/** |
|
523 |
* Sends the given request asynchronously using this client with the given |
|
524 |
* response body handler and push promise handler. |
|
525 |
* |
|
526 |
* <p> The returned completable future, if completed successfully, completes |
|
527 |
* with an {@link HttpResponse}{@code <T>} that contains the response status, |
|
528 |
* headers, and body ( as handled by given response body handler ). |
|
529 |
* |
|
530 |
* <p> {@linkplain PushPromiseHandler Push promises} received, if any, are |
|
531 |
* handled by the given {@code pushPromiseHandler}. A {@code null} valued |
|
532 |
* {@code pushPromiseHandler} rejects any push promises. |
|
533 |
* |
|
48083 | 534 |
* <p> The returned completable future completes exceptionally with: |
535 |
* <ul> |
|
536 |
* <li>{@link IOException} - if an I/O error occurs when sending or receiving</li> |
|
537 |
* <li>{@link IllegalArgumentException} - if the request method is not supported</li> |
|
538 |
* <li>{@link SecurityException} - If a security manager has been installed |
|
539 |
* and it denies {@link java.net.URLPermission access} to the |
|
540 |
* 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
|
541 |
* See <a href="#securitychecks">security checks</a> for further |
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
542 |
* information.</li> |
48083 | 543 |
* </ul> |
544 |
* |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
545 |
* @param <T> the response body type |
56025 | 546 |
* @param request the request |
56010 | 547 |
* @param responseBodyHandler the response body handler |
548 |
* @param pushPromiseHandler push promise handler, may be null |
|
549 |
* @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
|
550 |
*/ |
56010 | 551 |
public abstract <T> CompletableFuture<HttpResponse<T>> |
56025 | 552 |
sendAsync(HttpRequest request, |
56010 | 553 |
BodyHandler<T> responseBodyHandler, |
554 |
PushPromiseHandler<T> pushPromiseHandler); |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
555 |
|
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
556 |
/** |
48083 | 557 |
* 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
|
558 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
559 |
* <p> <b>Example</b> |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
560 |
* <pre>{@code HttpClient client = HttpClient.newHttpClient(); |
48083 | 561 |
* CompletableFuture<WebSocket> ws = client.newWebSocketBuilder() |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
562 |
* .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
|
563 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
564 |
* <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
|
565 |
* by using a custom {@code HttpClient}. |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
566 |
* |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
567 |
* <p> <b>Example</b> |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
568 |
* <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
|
569 |
* HttpClient client = HttpClient.newBuilder() |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
570 |
* .proxy(ProxySelector.of(addr)) |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
571 |
* .build(); |
48083 | 572 |
* CompletableFuture<WebSocket> ws = client.newWebSocketBuilder() |
56097
15dc43936d39
http-client-branch: javadoc refresh and minor fixes
chegar
parents:
56092
diff
changeset
|
573 |
* .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
|
574 |
* |
48083 | 575 |
* <p> A {@code WebSocket.Builder} returned from this method is not safe for |
576 |
* use by multiple threads without external synchronization. |
|
577 |
* |
|
578 |
* @implSpec The default implementation of this method throws |
|
579 |
* {@code UnsupportedOperationException}. Clients obtained through |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
580 |
* {@link HttpClient#newHttpClient()} or {@link HttpClient#newBuilder()} |
48083 | 581 |
* return a {@code WebSocket} builder. |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
582 |
* |
48083 | 583 |
* @implNote Both builder and {@code WebSocket}s created with it operate in |
584 |
* a non-blocking fashion. That is, their methods do not block before |
|
585 |
* returning a {@code CompletableFuture}. Asynchronous tasks are executed in |
|
586 |
* this {@code HttpClient}'s executor. |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
587 |
* |
48083 | 588 |
* <p> When a {@code CompletionStage} returned from |
589 |
* {@link WebSocket.Listener#onClose Listener.onClose} completes, |
|
590 |
* the {@code WebSocket} will send a Close message that has the same code |
|
591 |
* the received message has and an empty reason. |
|
592 |
* |
|
593 |
* @return a {@code WebSocket.Builder} |
|
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
594 |
* @throws UnsupportedOperationException |
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
595 |
* 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
|
596 |
*/ |
48083 | 597 |
public WebSocket.Builder newWebSocketBuilder() { |
42460
7133f144981a
8170648: Move java.net.http package out of Java SE to incubator namespace
michaelm
parents:
diff
changeset
|
598 |
throw new UnsupportedOperationException(); |
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 |
} |