1 /*
2 * Copyright (c) 2015, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.incubator.http;
27
28 import java.io.IOException;
29 import java.net.Authenticator;
30 import java.net.CookieManager;
31 import java.net.InetSocketAddress;
32 import java.net.ProxySelector;
33 import java.net.URI;
34 import java.util.Optional;
35 import java.util.concurrent.CompletableFuture;
36 import java.util.concurrent.Executor;
37 import javax.net.ssl.SSLContext;
38 import javax.net.ssl.SSLParameters;
39
40 /**
41 * A container for configuration information common to multiple {@link
42 * HttpRequest}s. All requests are sent through a {@code HttpClient}.
43 * {@Incubating}
44 *
45 * <p> {@code HttpClient}s are immutable and created from a builder returned
46 * from {@link HttpClient#newBuilder()}. Request builders are created by calling
47 * {@link HttpRequest#newBuilder() }.
48 * <p>
49 * See {@link HttpRequest} for examples of usage of this API.
50 *
51 * @since 9
52 */
53 public abstract class HttpClient {
54
55 /**
56 * Creates an HttpClient.
57 */
58 protected HttpClient() {}
59
60 /**
61 * Returns a new HttpClient with default settings.
62 *
63 * @return a new HttpClient
64 */
65 public static HttpClient newHttpClient() {
66 return new HttpClientBuilderImpl().build();
67 }
68
69 /**
70 * Creates a new {@code HttpClient} builder.
71 *
72 * @return a {@code HttpClient.Builder}
73 */
74 public static Builder newBuilder() {
75 return new HttpClientBuilderImpl();
76 }
77
78 /**
79 * A builder of immutable {@link HttpClient}s. {@code HttpClient.Builder}s
80 * are created by calling {@link HttpClient#newBuilder()}.
81 * {@Incubating}
82 *
83 * <p> Each of the setter methods in this class modifies the state of the
84 * builder and returns <i>this</i> (ie. the same instance). The methods are
85 * not synchronized and should not be called from multiple threads without
86 * external synchronization.
87 *
88 * <p> {@link #build()} returns a new {@code HttpClient} each time it is
89 * called.
90 *
91 * @since 9
92 */
93 public abstract static class Builder {
94
95 protected Builder() {}
96
97 /**
98 * Sets a cookie manager.
99 *
100 * @param cookieManager the cookie manager
101 * @return this builder
102 */
103 public abstract Builder cookieManager(CookieManager cookieManager);
104
105 /**
106 * Sets an {@code SSLContext}. If a security manager is set, then the caller
107 * must have the {@link java.net.NetPermission NetPermission}
108 * ({@code "setSSLContext"})
109 *
110 * <p> The effect of not calling this method, is that a default {@link
111 * javax.net.ssl.SSLContext} is used, which is normally adequate for
112 * client applications that do not need to specify protocols, or require
113 * client authentication.
114 *
115 * @param sslContext the SSLContext
116 * @return this builder
117 * @throws SecurityException if a security manager is set and the
118 * caller does not have any required permission
119 */
120 public abstract Builder sslContext(SSLContext sslContext);
121
122 /**
123 * Sets an {@code SSLParameters}. If this method is not called, then a default
124 * set of parameters are used. The contents of the given object are
125 * copied. Some parameters which are used internally by the HTTP protocol
126 * implementation (such as application protocol list) should not be set
127 * by callers, as they are ignored.
128 *
129 * @param sslParameters the SSLParameters
130 * @return this builder
131 */
132 public abstract Builder sslParameters(SSLParameters sslParameters);
133
134 /**
135 * Sets the executor to be used for asynchronous tasks. If this method is
136 * not called, a default executor is set, which is the one returned from {@link
137 * java.util.concurrent.Executors#newCachedThreadPool()
138 * Executors.newCachedThreadPool}.
139 *
140 * @param executor the Executor
141 * @return this builder
142 */
143 public abstract Builder executor(Executor executor);
144
145 /**
146 * Specifies whether requests will automatically follow redirects issued
147 * by the server. This setting can be overridden on each request. The
148 * default value for this setting is {@link Redirect#NEVER NEVER}
149 *
150 * @param policy the redirection policy
151 * @return this builder
152 */
153 public abstract Builder followRedirects(Redirect policy);
154
155 /**
156 * Requests a specific HTTP protocol version where possible. If not set,
157 * the version defaults to {@link HttpClient.Version#HTTP_2}. If
158 * {@link HttpClient.Version#HTTP_2} is set, then each request will
159 * attempt to upgrade to HTTP/2. If the upgrade succeeds, then the
160 * response to this request will use HTTP/2 and all subsequent requests
161 * and responses to the same
162 * <a href="https://tools.ietf.org/html/rfc6454#section-4">origin server</a>
163 * will use HTTP/2. If the upgrade fails, then the response will be
164 * handled using HTTP/1.1
165 *
166 * @param version the requested HTTP protocol version
167 * @return this builder
168 */
169 public abstract Builder version(HttpClient.Version version);
170
171 /**
172 * Sets the default priority for any HTTP/2 requests sent from this
173 * client. The value provided must be between {@code 1} and {@code 256}
174 * (inclusive).
175 *
176 * @param priority the priority weighting
177 * @return this builder
178 * @throws IllegalArgumentException if the given priority is out of range
179 */
180 public abstract Builder priority(int priority);
181
182 /**
183 * Sets a {@link java.net.ProxySelector} for this client. If no selector
184 * is set, then no proxies are used. If a {@code null} parameter is
185 * given then the system wide default proxy selector is used.
186 *
187 * @implNote {@link java.net.ProxySelector#of(InetSocketAddress)}
188 * provides a {@code ProxySelector} which uses one proxy for all requests.
189 *
190 * @param selector the ProxySelector
191 * @return this builder
192 */
193 public abstract Builder proxy(ProxySelector selector);
194
195 /**
196 * Sets an authenticator to use for HTTP authentication.
197 *
198 * @param a the Authenticator
199 * @return this builder
200 */
201 public abstract Builder authenticator(Authenticator a);
202
203 /**
204 * Returns a {@link HttpClient} built from the current state of this
205 * builder.
206 *
207 * @return this builder
208 */
209 public abstract HttpClient build();
210 }
211
212
213 /**
214 * Returns an {@code Optional} which contains this client's {@link
215 * CookieManager}. If no {@code CookieManager} was set in this client's builder,
216 * then the {@code Optional} is empty.
217 *
218 * @return an {@code Optional} containing this client's {@code CookieManager}
219 */
220 public abstract Optional<CookieManager> cookieManager();
221
222 /**
223 * Returns the follow-redirects setting for this client. The default value
224 * for this setting is {@link HttpClient.Redirect#NEVER}
225 *
226 * @return this client's follow redirects setting
227 */
228 public abstract Redirect followRedirects();
229
230 /**
231 * Returns an {@code Optional} containing the {@code ProxySelector} for this client.
232 * If no proxy is set then the {@code Optional} is empty.
233 *
234 * @return an {@code Optional} containing this client's proxy selector
235 */
236 public abstract Optional<ProxySelector> proxy();
237
238 /**
239 * Returns the {@code SSLContext}, if one was set on this client. If a security
240 * manager is set, then the caller must have the
241 * {@link java.net.NetPermission NetPermission}("getSSLContext") permission.
242 * If no {@code SSLContext} was set, then the default context is returned.
243 *
244 * @return this client's SSLContext
245 * @throws SecurityException if the caller does not have permission to get
246 * the SSLContext
247 */
248 public abstract SSLContext sslContext();
249
250 /**
251 * Returns an {@code Optional} containing the {@link SSLParameters} set on
252 * this client. If no {@code SSLParameters} were set in the client's builder,
253 * then the {@code Optional} is empty.
254 *
255 * @return an {@code Optional} containing this client's {@code SSLParameters}
256 */
257 public abstract Optional<SSLParameters> sslParameters();
258
259 /**
260 * Returns an {@code Optional} containing the {@link Authenticator} set on
261 * this client. If no {@code Authenticator} was set in the client's builder,
262 * then the {@code Optional} is empty.
263 *
264 * @return an {@code Optional} containing this client's {@code Authenticator}
265 */
266 public abstract Optional<Authenticator> authenticator();
267
268 /**
269 * Returns the HTTP protocol version requested for this client. The default
270 * value is {@link HttpClient.Version#HTTP_2}
271 *
272 * @return the HTTP protocol version requested
273 */
274 public abstract HttpClient.Version version();
275
276 /**
277 * Returns the {@code Executor} set on this client. If an {@code
278 * Executor} was not set on the client's builder, then a default
279 * object is returned. The default {@code Executor} is created independently
280 * for each client.
281 *
282 * @return this client's Executor
283 */
284 public abstract Executor executor();
285
286 /**
287 * The HTTP protocol version.
288 * {@Incubating}
289 *
290 * @since 9
291 */
292 public enum Version {
293
294 /**
295 * HTTP version 1.1
296 */
297 HTTP_1_1,
298
299 /**
300 * HTTP version 2
301 */
302 HTTP_2
303 }
304
332 * to other HTTP URLs, and from HTTPS URLs to other HTTPS URLs.
333 */
334 SAME_PROTOCOL,
335
336 /**
337 * Redirect always except from HTTPS URLs to HTTP URLs.
338 */
339 SECURE
340 }
341
342 /**
343 * Sends the given request using this client, blocking if necessary to get
344 * the response. The returned {@link HttpResponse}{@code <T>} contains the
345 * response status, headers, and body ( as handled by given response body
346 * handler ).
347 *
348 * @param <T> the response body type
349 * @param req the request
350 * @param responseBodyHandler the response body handler
351 * @return the response body
352 * @throws java.io.IOException if an I/O error occurs when sending or receiving
353 * @throws java.lang.InterruptedException if the operation is interrupted
354 */
355 public abstract <T> HttpResponse<T>
356 send(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler)
357 throws IOException, InterruptedException;
358
359 /**
360 * Sends the given request asynchronously using this client and the given
361 * response handler.
362 *
363 * @param <T> the response body type
364 * @param req the request
365 * @param responseBodyHandler the response body handler
366 * @return a {@code CompletableFuture<HttpResponse<T>>}
367 */
368 public abstract <T> CompletableFuture<HttpResponse<T>>
369 sendAsync(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler);
370
371 /**
372 * Sends the given request asynchronously using this client and the given
373 * multi response handler.
374 *
375 * @param <U> a type representing the aggregated results
376 * @param <T> a type representing all of the response bodies
377 * @param req the request
378 * @param multiProcessor the MultiProcessor for the request
379 * @return a {@code CompletableFuture<U>}
380 */
381 public abstract <U, T> CompletableFuture<U>
382 sendAsync(HttpRequest req, HttpResponse.MultiProcessor<U, T> multiProcessor);
383
384 /**
385 * Creates a builder of {@link WebSocket} instances connected to the given
386 * URI and receiving events and messages with the given {@code Listener}.
387 *
388 * <p> <b>Example</b>
389 * <pre>{@code
390 * HttpClient client = HttpClient.newHttpClient();
391 * WebSocket.Builder builder = client.newWebSocketBuilder(
392 * URI.create("ws://websocket.example.com"),
393 * listener);
394 * }</pre>
395 *
396 * <p> Finer control over the WebSocket Opening Handshake can be achieved
397 * by using a custom {@code HttpClient}.
398 *
399 * <p> <b>Example</b>
400 * <pre>{@code
401 * InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
402 * HttpClient client = HttpClient.newBuilder()
403 * .proxy(ProxySelector.of(addr))
404 * .build();
405 * WebSocket.Builder builder = client.newWebSocketBuilder(
406 * URI.create("ws://websocket.example.com"),
407 * listener);
408 * }</pre>
409 *
410 * @implSpec The default implementation of this method throws {@code
411 * UnsupportedOperationException}. However, clients obtained through
412 * {@link HttpClient#newHttpClient()} or {@link HttpClient#newBuilder()}
413 * provide WebSocket capability.
414 *
415 * @param uri
416 * the WebSocket URI
417 * @param listener
418 * the listener
419 *
420 * @return a builder of {@code WebSocket} instances
421 * @throws UnsupportedOperationException
422 * if this {@code HttpClient} does not provide WebSocket support
423 */
424 public WebSocket.Builder newWebSocketBuilder(URI uri,
425 WebSocket.Listener listener)
426 {
427 throw new UnsupportedOperationException();
428 }
429 }
|
1 /*
2 * Copyright (c) 2015, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.incubator.http;
27
28 import java.io.IOException;
29 import java.net.Authenticator;
30 import java.net.CookieHandler;
31 import java.net.InetSocketAddress;
32 import java.net.Proxy;
33 import java.net.ProxySelector;
34 import java.net.URI;
35 import java.util.Optional;
36 import java.util.concurrent.CompletableFuture;
37 import java.util.concurrent.Executor;
38 import java.util.concurrent.Executors;
39 import java.util.concurrent.ThreadFactory;
40 import javax.net.ssl.SSLContext;
41 import javax.net.ssl.SSLParameters;
42
43 /**
44 * A container for configuration information common to multiple {@link
45 * HttpRequest}s. All requests are sent through a {@code HttpClient}.
46 * {@Incubating}
47 *
48 * <p> {@code HttpClient}s are immutable and created from a builder returned
49 * from {@link HttpClient#newBuilder()}. Request builders are created by calling
50 * {@link HttpRequest#newBuilder() }.
51 * <p>
52 * See {@link HttpRequest} for examples of usage of this API.
53 *
54 * @since 9
55 */
56 public abstract class HttpClient {
57
58 /**
59 * Creates an HttpClient.
60 */
61 protected HttpClient() {}
62
63 /**
64 * Returns a new HttpClient with default settings.
65 *
66 * <p> Equivalent to {@code newBuilder().build()}.
67 *
68 * <p> The default settings include: the "GET" request method, a preference
69 * of {@linkplain HttpClient.Version#HTTP_2 HTTP/2}, a redirection policy of
70 * {@linkplain Redirect#NEVER NEVER}, the {@linkplain
71 * ProxySelector#getDefault() default proxy selector}, and the {@linkplain
72 * SSLContext#getDefault() default SSL context}.
73 *
74 * @implNote The system-wide default values are retrieved at the time the
75 * {@code HttpClient} instance is constructed. Changing the system-wide
76 * values after an {@code HttpClient} instance has been built, for
77 * instance, by calling {@link ProxySelector#setDefault(ProxySelector)}
78 * or {@link SSLContext#setDefault(SSLContext)}, has no effect on already
79 * built instances.
80 *
81 * @return a new HttpClient
82 */
83 public static HttpClient newHttpClient() {
84 return newBuilder().build();
85 }
86
87 /**
88 * Creates a new {@code HttpClient} builder.
89 *
90 * @return a {@code HttpClient.Builder}
91 */
92 public static Builder newBuilder() {
93 return new HttpClientBuilderImpl();
94 }
95
96 /**
97 * A builder of immutable {@link HttpClient}s.
98 * {@Incubating}
99 *
100 * <p> Builders are created by invoking {@linkplain HttpClient#newBuilder()
101 * newBuilder}. Each of the setter methods modifies the state of the builder
102 * and returns the same instance. Builders are not thread-safe and should not be
103 * used concurrently from multiple threads without external synchronization.
104 *
105 * @since 9
106 */
107 public abstract static class Builder {
108
109 /**
110 * A proxy selector that always return {@link Proxy#NO_PROXY} implying
111 * a direct connection.
112 * This is a convenience object that can be passed to {@link #proxy(ProxySelector)}
113 * in order to build an instance of {@link HttpClient} that uses no
114 * proxy.
115 */
116 public static final ProxySelector NO_PROXY = ProxySelector.of(null);
117
118 /**
119 * Creates a Builder.
120 */
121 protected Builder() {}
122
123 /**
124 * Sets a cookie handler.
125 *
126 * @param cookieHandler the cookie handler
127 * @return this builder
128 */
129 public abstract Builder cookieHandler(CookieHandler cookieHandler);
130
131 /**
132 * Sets an {@code SSLContext}.
133 *
134 * <p> If this method is not invoked prior to {@linkplain #build()
135 * building}, then newly built clients will use the {@linkplain
136 * SSLContext#getDefault() default context}, which is normally adequate
137 * for client applications that do not need to specify protocols, or
138 * require client authentication.
139 *
140 * @param sslContext the SSLContext
141 * @return this builder
142 */
143 public abstract Builder sslContext(SSLContext sslContext);
144
145 /**
146 * Sets an {@code SSLParameters}.
147 *
148 * <p> If this method is not invoked prior to {@linkplain #build()
149 * building}, then newly built clients will use a default,
150 * implementation specific, set of parameters.
151 *
152 * <p> Some parameters which are used internally by the HTTP Client
153 * implementation (such as the application protocol list) should not be
154 * set by callers, as they may be ignored. The contents of the given
155 * object are copied.
156 *
157 * @param sslParameters the SSLParameters
158 * @return this builder
159 */
160 public abstract Builder sslParameters(SSLParameters sslParameters);
161
162 /**
163 * Sets the executor to be used for asynchronous and dependent tasks.
164 *
165 * <p> If this method is not invoked prior to {@linkplain #build()
166 * building}, a default executor is created for each newly built {@code
167 * HttpClient}. The default executor uses a {@linkplain
168 * Executors#newCachedThreadPool(ThreadFactory) cached thread pool},
169 * with a custom thread factory.
170 *
171 * @implNote If a security manager has been installed, the thread
172 * factory creates threads that run with an access control context that
173 * has no permissions.
174 *
175 * @param executor the Executor
176 * @return this builder
177 */
178 public abstract Builder executor(Executor executor);
179
180 /**
181 * Specifies whether requests will automatically follow redirects issued
182 * by the server.
183 *
184 * <p> If this method is not invoked prior to {@linkplain #build()
185 * building}, then newly built clients will use a default redirection
186 * policy of {@link Redirect#NEVER NEVER}.
187 *
188 * @param policy the redirection policy
189 * @return this builder
190 */
191 public abstract Builder followRedirects(Redirect policy);
192
193 /**
194 * Requests a specific HTTP protocol version where possible.
195 *
196 * <p> If this method is not invoked prior to {@linkplain #build()
197 * building}, then newly built clients will prefer {@linkplain
198 * Version#HTTP_2 HTTP/2}.
199 *
200 * <p> If set to {@linkplain Version#HTTP_2 HTTP/2}, then each request
201 * will attempt to upgrade to HTTP/2. If the upgrade succeeds, then the
202 * response to this request will use HTTP/2 and all subsequent requests
203 * and responses to the same
204 * <a href="https://tools.ietf.org/html/rfc6454#section-4">origin server</a>
205 * will use HTTP/2. If the upgrade fails, then the response will be
206 * handled using HTTP/1.1
207 *
208 * @param version the requested HTTP protocol version
209 * @return this builder
210 */
211 public abstract Builder version(HttpClient.Version version);
212
213 /**
214 * Sets the default priority for any HTTP/2 requests sent from this
215 * client. The value provided must be between {@code 1} and {@code 256}
216 * (inclusive).
217 *
218 * @param priority the priority weighting
219 * @return this builder
220 * @throws IllegalArgumentException if the given priority is out of range
221 */
222 public abstract Builder priority(int priority);
223
224 /**
225 * Sets a {@link java.net.ProxySelector}.
226 *
227 * @apiNote {@link ProxySelector#of(InetSocketAddress)}
228 * provides a {@code ProxySelector} which uses a single proxy for all
229 * requests. The system-wide proxy selector can be retrieved by
230 * {@link ProxySelector#getDefault()}.
231 *
232 * @implNote
233 * If this method is not invoked prior to {@linkplain #build()
234 * building}, then newly built clients will use the {@linkplain
235 * ProxySelector#getDefault() default proxy selector}, which
236 * is normally adequate for client applications. This default
237 * behavior can be turned off by supplying an explicit proxy
238 * selector to this method, such as {@link #NO_PROXY} or one
239 * returned by {@link ProxySelector#of(InetSocketAddress)},
240 * before calling {@link #build()}.
241 *
242 * @param selector the ProxySelector
243 * @return this builder
244 */
245 public abstract Builder proxy(ProxySelector selector);
246
247 /**
248 * Sets an authenticator to use for HTTP authentication.
249 *
250 * @param a the Authenticator
251 * @return this builder
252 */
253 public abstract Builder authenticator(Authenticator a);
254
255 /**
256 * Returns a new {@link HttpClient} built from the current state of this
257 * builder.
258 *
259 * @return this builder
260 */
261 public abstract HttpClient build();
262 }
263
264
265 /**
266 * Returns an {@code Optional} containing this client's {@linkplain
267 * CookieHandler}. If no {@code CookieHandler} was set in this client's
268 * builder, then the {@code Optional} is empty.
269 *
270 * @return an {@code Optional} containing this client's {@code CookieHandler}
271 */
272 public abstract Optional<CookieHandler> cookieHandler();
273
274 /**
275 * Returns the follow redirects policy for this client. The default value
276 * for client's built by builders that do not specify a redirect policy is
277 * {@link HttpClient.Redirect#NEVER NEVER}.
278 *
279 * @return this client's follow redirects setting
280 */
281 public abstract Redirect followRedirects();
282
283 /**
284 * Returns an {@code Optional} containing the {@code ProxySelector}
285 * supplied to this client. If no proxy selector was set in this client's
286 * builder, then the {@code Optional} is empty.
287 *
288 * <p> Even though this method may return an empty optional, the {@code
289 * HttpClient} may still have an non-exposed {@linkplain
290 * Builder#proxy(ProxySelector) default proxy selector} that is
291 * used for sending HTTP requests.
292 *
293 * @return an {@code Optional} containing the proxy selector supplied
294 * to this client.
295 */
296 public abstract Optional<ProxySelector> proxy();
297
298 /**
299 * Returns this client's {@code SSLContext}.
300 *
301 * <p> If no {@code SSLContext} was set in this client's builder, then the
302 * {@linkplain SSLContext#getDefault() default context} is returned.
303 *
304 * @return this client's SSLContext
305 */
306 public abstract SSLContext sslContext();
307
308 /**
309 * Returns a copy of this client's {@link SSLParameters}.
310 *
311 * <p> If no {@code SSLParameters} were set in the client's builder, then an
312 * implementation specific default set of parameters, that the client will
313 * use, is returned.
314 *
315 * @return this client's {@code SSLParameters}
316 */
317 public abstract SSLParameters sslParameters();
318
319 /**
320 * Returns an {@code Optional} containing the {@link Authenticator} set on
321 * this client. If no {@code Authenticator} was set in the client's builder,
322 * then the {@code Optional} is empty.
323 *
324 * @return an {@code Optional} containing this client's {@code Authenticator}
325 */
326 public abstract Optional<Authenticator> authenticator();
327
328 /**
329 * Returns the HTTP protocol version requested for this client. The default
330 * value is {@link HttpClient.Version#HTTP_2}
331 *
332 * @return the HTTP protocol version requested
333 */
334 public abstract HttpClient.Version version();
335
336 /**
337 * Returns an {@code Optional} containing this client's {@linkplain
338 * Executor}. If no {@code Executor} was set in the client's builder,
339 * then the {@code Optional} is empty.
340 *
341 * <p> Even though this method may return an empty optional, the {@code
342 * HttpClient} may still have an non-exposed {@linkplain
343 * HttpClient.Builder#executor(Executor) default executor} that is used for
344 * executing asynchronous and dependent tasks.
345 *
346 * @return an {@code Optional} containing this client's {@code Executor}
347 */
348 public abstract Optional<Executor> executor();
349
350 /**
351 * The HTTP protocol version.
352 * {@Incubating}
353 *
354 * @since 9
355 */
356 public enum Version {
357
358 /**
359 * HTTP version 1.1
360 */
361 HTTP_1_1,
362
363 /**
364 * HTTP version 2
365 */
366 HTTP_2
367 }
368
396 * to other HTTP URLs, and from HTTPS URLs to other HTTPS URLs.
397 */
398 SAME_PROTOCOL,
399
400 /**
401 * Redirect always except from HTTPS URLs to HTTP URLs.
402 */
403 SECURE
404 }
405
406 /**
407 * Sends the given request using this client, blocking if necessary to get
408 * the response. The returned {@link HttpResponse}{@code <T>} contains the
409 * response status, headers, and body ( as handled by given response body
410 * handler ).
411 *
412 * @param <T> the response body type
413 * @param req the request
414 * @param responseBodyHandler the response body handler
415 * @return the response body
416 * @throws IOException if an I/O error occurs when sending or receiving
417 * @throws InterruptedException if the operation is interrupted
418 * @throws IllegalArgumentException if the request method is not supported
419 * @throws SecurityException If a security manager has been installed
420 * and it denies {@link java.net.URLPermission access} to the
421 * URL in the given request, or proxy if one is configured.
422 * See HttpRequest for further information about
423 * <a href="HttpRequest.html#securitychecks">security checks</a>.
424 */
425 public abstract <T> HttpResponse<T>
426 send(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler)
427 throws IOException, InterruptedException;
428
429 /**
430 * Sends the given request asynchronously using this client and the given
431 * response handler.
432 *
433 * <p> The returned completable future completes exceptionally with:
434 * <ul>
435 * <li>{@link IOException} - if an I/O error occurs when sending or receiving</li>
436 * <li>{@link IllegalArgumentException} - if the request method is not supported</li>
437 * <li>{@link SecurityException} - If a security manager has been installed
438 * and it denies {@link java.net.URLPermission access} to the
439 * URL in the given request, or proxy if one is configured.
440 * See HttpRequest for further information about
441 * <a href="HttpRequest.html#securitychecks">security checks</a>.</li>
442 * </ul>
443 *
444 * @param <T> the response body type
445 * @param req the request
446 * @param responseBodyHandler the response body handler
447 * @return a {@code CompletableFuture<HttpResponse<T>>}
448 */
449 public abstract <T> CompletableFuture<HttpResponse<T>>
450 sendAsync(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler);
451
452 /**
453 * Sends the given request asynchronously using this client and the given
454 * multi response handler.
455 *
456 * <p> The returned completable future completes exceptionally with:
457 * <ul>
458 * <li>{@link IOException} - if an I/O error occurs when sending or receiving</li>
459 * <li>{@link IllegalArgumentException} - if the request method is not supported</li>
460 * <li>{@link SecurityException} - If a security manager has been installed
461 * and it denies {@link java.net.URLPermission access} to the
462 * URL in the given request, or proxy if one is configured.
463 * See HttpRequest for further information about
464 * <a href="HttpRequest.html#securitychecks">security checks</a>.</li>
465 * </ul>
466 *
467 * @param <U> a type representing the aggregated results
468 * @param <T> a type representing all of the response bodies
469 * @param req the request
470 * @param multiSubscriber the multiSubscriber for the request
471 * @return a {@code CompletableFuture<U>}
472 */
473 public abstract <U, T> CompletableFuture<U>
474 sendAsync(HttpRequest req, HttpResponse.MultiSubscriber<U, T> multiSubscriber);
475
476 /**
477 * Creates a new {@code WebSocket} builder (optional operation).
478 *
479 * <p> <b>Example</b>
480 * <pre>{@code
481 * HttpClient client = HttpClient.newHttpClient();
482 * CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
483 * .buildAsync(URI.create("ws://websocket.example.com"), listener);
484 * }</pre>
485 *
486 * <p> Finer control over the WebSocket Opening Handshake can be achieved
487 * by using a custom {@code HttpClient}.
488 *
489 * <p> <b>Example</b>
490 * <pre>{@code
491 * InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
492 * HttpClient client = HttpClient.newBuilder()
493 * .proxy(ProxySelector.of(addr))
494 * .build();
495 * CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
496 * .buildAsync(URI.create("ws://websocket.example.com"), listener);
497 * }</pre>
498 *
499 * <p> A {@code WebSocket.Builder} returned from this method is not safe for
500 * use by multiple threads without external synchronization.
501 *
502 * @implSpec The default implementation of this method throws
503 * {@code UnsupportedOperationException}. Clients obtained through
504 * {@link HttpClient#newHttpClient()} or {@link HttpClient#newBuilder()}
505 * return a {@code WebSocket} builder.
506 *
507 * @implNote Both builder and {@code WebSocket}s created with it operate in
508 * a non-blocking fashion. That is, their methods do not block before
509 * returning a {@code CompletableFuture}. Asynchronous tasks are executed in
510 * this {@code HttpClient}'s executor.
511 *
512 * <p> When a {@code CompletionStage} returned from
513 * {@link WebSocket.Listener#onClose Listener.onClose} completes,
514 * the {@code WebSocket} will send a Close message that has the same code
515 * the received message has and an empty reason.
516 *
517 * @return a {@code WebSocket.Builder}
518 * @throws UnsupportedOperationException
519 * if this {@code HttpClient} does not provide WebSocket support
520 */
521 public WebSocket.Builder newWebSocketBuilder() {
522 throw new UnsupportedOperationException();
523 }
524 }
|