101 * @return this builder |
103 * @return this builder |
102 */ |
104 */ |
103 public abstract Builder cookieManager(CookieManager cookieManager); |
105 public abstract Builder cookieManager(CookieManager cookieManager); |
104 |
106 |
105 /** |
107 /** |
106 * Sets an {@code SSLContext}. If a security manager is set, then the caller |
108 * Sets an {@code SSLContext}. |
107 * must have the {@link java.net.NetPermission NetPermission} |
109 * |
108 * ({@code "setSSLContext"}) |
110 * <p> If this method is not invoked before {@linkplain #build() build}, |
109 * |
111 * then the {@link SSLContext#getDefault() default context} is used, |
110 * <p> The effect of not calling this method, is that a default {@link |
112 * which is normally adequate for client applications that do not need |
111 * javax.net.ssl.SSLContext} is used, which is normally adequate for |
113 * to specify protocols, or require client authentication. |
112 * client applications that do not need to specify protocols, or require |
|
113 * client authentication. |
|
114 * |
114 * |
115 * @param sslContext the SSLContext |
115 * @param sslContext the SSLContext |
116 * @return this builder |
116 * @return this builder |
117 * @throws SecurityException if a security manager is set and the |
117 * @throws SecurityException if a security manager has been installed |
118 * caller does not have any required permission |
118 * and it denies {@linkplain java.net.NetPermission} |
|
119 * ({@code "setSSLContext"}) |
119 */ |
120 */ |
120 public abstract Builder sslContext(SSLContext sslContext); |
121 public abstract Builder sslContext(SSLContext sslContext); |
121 |
122 |
122 /** |
123 /** |
123 * Sets an {@code SSLParameters}. If this method is not called, then a default |
124 * Sets an {@code SSLParameters}. |
124 * set of parameters are used. The contents of the given object are |
125 * |
125 * copied. Some parameters which are used internally by the HTTP protocol |
126 * <p> If this method is not invoked before {@linkplain #build() build}, |
126 * implementation (such as application protocol list) should not be set |
127 * then a default, implementation specific, set of parameters are used. |
127 * by callers, as they are ignored. |
128 * |
|
129 * <p> Some parameters which are used internally by the HTTP Client |
|
130 * implementation (such as the application protocol list) should not be |
|
131 * set by callers, as they may be ignored. The contents of the given |
|
132 * object are copied. |
128 * |
133 * |
129 * @param sslParameters the SSLParameters |
134 * @param sslParameters the SSLParameters |
130 * @return this builder |
135 * @return this builder |
131 */ |
136 */ |
132 public abstract Builder sslParameters(SSLParameters sslParameters); |
137 public abstract Builder sslParameters(SSLParameters sslParameters); |
133 |
138 |
134 /** |
139 /** |
135 * Sets the executor to be used for asynchronous tasks. If this method is |
140 * Sets the executor to be used for asynchronous and dependent tasks. |
136 * not called, a default executor is set, which is the one returned from {@link |
141 * |
137 * java.util.concurrent.Executors#newCachedThreadPool() |
142 * <p> If this method is not invoked before {@linkplain #build() build}, |
138 * Executors.newCachedThreadPool}. |
143 * a default executor is created for each newly built {@code HttpClient}. |
|
144 * The default executor uses a {@linkplain |
|
145 * Executors#newCachedThreadPool(ThreadFactory) cached thread pool}, with |
|
146 * a custom thread factory. |
|
147 * |
|
148 * @implNote If a security manager has been installed, the thread |
|
149 * factory creates threads that run with an access control context that |
|
150 * has no permissions. |
139 * |
151 * |
140 * @param executor the Executor |
152 * @param executor the Executor |
141 * @return this builder |
153 * @return this builder |
142 */ |
154 */ |
143 public abstract Builder executor(Executor executor); |
155 public abstract Builder executor(Executor executor); |
144 |
156 |
145 /** |
157 /** |
146 * Specifies whether requests will automatically follow redirects issued |
158 * Specifies whether requests will automatically follow redirects issued |
147 * by the server. This setting can be overridden on each request. The |
159 * by the server. The default redirection policy for clients built by |
148 * default value for this setting is {@link Redirect#NEVER NEVER} |
160 * this builder, if this method has not been invoked, is {@link |
|
161 * Redirect#NEVER NEVER}. |
149 * |
162 * |
150 * @param policy the redirection policy |
163 * @param policy the redirection policy |
151 * @return this builder |
164 * @return this builder |
152 */ |
165 */ |
153 public abstract Builder followRedirects(Redirect policy); |
166 public abstract Builder followRedirects(Redirect policy); |
178 * @throws IllegalArgumentException if the given priority is out of range |
191 * @throws IllegalArgumentException if the given priority is out of range |
179 */ |
192 */ |
180 public abstract Builder priority(int priority); |
193 public abstract Builder priority(int priority); |
181 |
194 |
182 /** |
195 /** |
183 * Sets a {@link java.net.ProxySelector} for this client. If no selector |
196 * Sets a {@link java.net.ProxySelector}. |
184 * is set, then no proxies are used. If a {@code null} parameter is |
197 * |
185 * given then the system wide default proxy selector is used. |
198 * @implNote {@link ProxySelector#of(InetSocketAddress)} |
186 * |
199 * provides a {@code ProxySelector} which uses a single proxy for all |
187 * @implNote {@link java.net.ProxySelector#of(InetSocketAddress)} |
200 * requests. The system-wide proxy selector can be retrieved by |
188 * provides a {@code ProxySelector} which uses one proxy for all requests. |
201 * {@link ProxySelector#getDefault()}. |
189 * |
202 * |
190 * @param selector the ProxySelector |
203 * @param selector the ProxySelector |
191 * @return this builder |
204 * @return this builder |
192 */ |
205 */ |
193 public abstract Builder proxy(ProxySelector selector); |
206 public abstract Builder proxy(ProxySelector selector); |
209 public abstract HttpClient build(); |
222 public abstract HttpClient build(); |
210 } |
223 } |
211 |
224 |
212 |
225 |
213 /** |
226 /** |
214 * Returns an {@code Optional} which contains this client's {@link |
227 * Returns an {@code Optional} containing this client's {@link |
215 * CookieManager}. If no {@code CookieManager} was set in this client's builder, |
228 * CookieManager}. If no {@code CookieManager} was set in this client's |
216 * then the {@code Optional} is empty. |
229 * builder, then the {@code Optional} is empty. |
217 * |
230 * |
218 * @return an {@code Optional} containing this client's {@code CookieManager} |
231 * @return an {@code Optional} containing this client's {@code CookieManager} |
219 */ |
232 */ |
220 public abstract Optional<CookieManager> cookieManager(); |
233 public abstract Optional<CookieManager> cookieManager(); |
221 |
234 |
222 /** |
235 /** |
223 * Returns the follow-redirects setting for this client. The default value |
236 * Returns the follow redirects policy for this client. The default value |
224 * for this setting is {@link HttpClient.Redirect#NEVER} |
237 * for client's built by builders that do not specify a redirect policy is |
|
238 * {@link HttpClient.Redirect#NEVER NEVER}. |
225 * |
239 * |
226 * @return this client's follow redirects setting |
240 * @return this client's follow redirects setting |
227 */ |
241 */ |
228 public abstract Redirect followRedirects(); |
242 public abstract Redirect followRedirects(); |
229 |
243 |
230 /** |
244 /** |
231 * Returns an {@code Optional} containing the {@code ProxySelector} for this client. |
245 * Returns an {@code Optional} containing this client's {@code ProxySelector}. |
232 * If no proxy is set then the {@code Optional} is empty. |
246 * If no proxy selector was set in this client's builder, then the {@code |
|
247 * Optional} is empty. |
233 * |
248 * |
234 * @return an {@code Optional} containing this client's proxy selector |
249 * @return an {@code Optional} containing this client's proxy selector |
235 */ |
250 */ |
236 public abstract Optional<ProxySelector> proxy(); |
251 public abstract Optional<ProxySelector> proxy(); |
237 |
252 |
238 /** |
253 /** |
239 * Returns the {@code SSLContext}, if one was set on this client. If a security |
254 * Returns this client's {@code SSLContext}. |
240 * manager is set, then the caller must have the |
255 * |
241 * {@link java.net.NetPermission NetPermission}("getSSLContext") permission. |
256 * <p> If no {@code SSLContext} was set in this client's builder, then the |
242 * If no {@code SSLContext} was set, then the default context is returned. |
257 * {@linkplain SSLContext#getDefault() default context} is returned. |
243 * |
258 * |
244 * @return this client's SSLContext |
259 * @return this client's SSLContext |
245 * @throws SecurityException if the caller does not have permission to get |
260 * @throws SecurityException if a security manager has been installed |
246 * the SSLContext |
261 * and it denies {@linkplain java.net.NetPermission} |
|
262 * ({@code "getSSLContext"}) |
247 */ |
263 */ |
248 public abstract SSLContext sslContext(); |
264 public abstract SSLContext sslContext(); |
249 |
265 |
250 /** |
266 /** |
251 * Returns an {@code Optional} containing the {@link SSLParameters} set on |
267 * Returns a copy of this client's {@link SSLParameters}. |
252 * this client. If no {@code SSLParameters} were set in the client's builder, |
268 * |
253 * then the {@code Optional} is empty. |
269 * <p> If no {@code SSLParameters} were set in the client's builder, then an |
254 * |
270 * implementation specific default set of parameters, that the client will |
255 * @return an {@code Optional} containing this client's {@code SSLParameters} |
271 * use, is returned. |
256 */ |
272 * |
257 public abstract Optional<SSLParameters> sslParameters(); |
273 * @return this client's {@code SSLParameters} |
|
274 */ |
|
275 public abstract SSLParameters sslParameters(); |
258 |
276 |
259 /** |
277 /** |
260 * Returns an {@code Optional} containing the {@link Authenticator} set on |
278 * Returns an {@code Optional} containing the {@link Authenticator} set on |
261 * this client. If no {@code Authenticator} was set in the client's builder, |
279 * this client. If no {@code Authenticator} was set in the client's builder, |
262 * then the {@code Optional} is empty. |
280 * then the {@code Optional} is empty. |
272 * @return the HTTP protocol version requested |
290 * @return the HTTP protocol version requested |
273 */ |
291 */ |
274 public abstract HttpClient.Version version(); |
292 public abstract HttpClient.Version version(); |
275 |
293 |
276 /** |
294 /** |
277 * Returns the {@code Executor} set on this client. If an {@code |
295 * Returns an {@code Optional} containing this client's {@linkplain |
278 * Executor} was not set on the client's builder, then a default |
296 * Executor}. If no {@code Executor} was set in the client's builder, |
279 * object is returned. The default {@code Executor} is created independently |
297 * then the {@code Optional} is empty. |
280 * for each client. |
298 * |
281 * |
299 * <p> Even though this method may return an empty optional, the {@code |
282 * @return this client's Executor |
300 * HttpClient} may still have an non-exposed {@linkplain |
283 */ |
301 * HttpClient.Builder#executor(Executor) default executor} that is used for |
284 public abstract Executor executor(); |
302 * executing asynchronous and dependent tasks. |
|
303 * |
|
304 * @return an {@code Optional} containing this client's {@code Executor} |
|
305 */ |
|
306 public abstract Optional<Executor> executor(); |
285 |
307 |
286 /** |
308 /** |
287 * The HTTP protocol version. |
309 * The HTTP protocol version. |
288 * {@Incubating} |
310 * {@Incubating} |
289 * |
311 * |
349 * @param req the request |
371 * @param req the request |
350 * @param responseBodyHandler the response body handler |
372 * @param responseBodyHandler the response body handler |
351 * @return the response body |
373 * @return the response body |
352 * @throws java.io.IOException if an I/O error occurs when sending or receiving |
374 * @throws java.io.IOException if an I/O error occurs when sending or receiving |
353 * @throws java.lang.InterruptedException if the operation is interrupted |
375 * @throws java.lang.InterruptedException if the operation is interrupted |
|
376 * @throws SecurityException If a security manager has been installed |
|
377 * and it denies {@link java.net.URLPermission access} to the |
|
378 * URL in the given request, or proxy if one is configured. |
|
379 * See HttpRequest for further information about |
|
380 * <a href="HttpRequest.html#securitychecks">security checks</a>. |
354 */ |
381 */ |
355 public abstract <T> HttpResponse<T> |
382 public abstract <T> HttpResponse<T> |
356 send(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler) |
383 send(HttpRequest req, HttpResponse.BodyHandler<T> responseBodyHandler) |
357 throws IOException, InterruptedException; |
384 throws IOException, InterruptedException; |
358 |
385 |
359 /** |
386 /** |
360 * Sends the given request asynchronously using this client and the given |
387 * Sends the given request asynchronously using this client and the given |
361 * response handler. |
388 * response handler. |
|
389 * |
|
390 * <p> The returned completable future is completed with a SecurityException |
|
391 * if a security manager has been installed and it denies {@link |
|
392 * java.net.URLPermission access} to the URI in the given request, or proxy |
|
393 * if one is configured. See HttpRequest for further information about |
|
394 * <a href="HttpRequest.html#securitychecks">security checks</a>. |
362 * |
395 * |
363 * @param <T> the response body type |
396 * @param <T> the response body type |
364 * @param req the request |
397 * @param req the request |
365 * @param responseBodyHandler the response body handler |
398 * @param responseBodyHandler the response body handler |
366 * @return a {@code CompletableFuture<HttpResponse<T>>} |
399 * @return a {@code CompletableFuture<HttpResponse<T>>} |
370 |
403 |
371 /** |
404 /** |
372 * Sends the given request asynchronously using this client and the given |
405 * Sends the given request asynchronously using this client and the given |
373 * multi response handler. |
406 * multi response handler. |
374 * |
407 * |
|
408 * <p> The returned completable future is completed with a SecurityException |
|
409 * if a security manager has been installed and it denies {@link |
|
410 * java.net.URLPermission access} to the URI in the given request, or proxy |
|
411 * if one is configured. See HttpRequest for further information about |
|
412 * <a href="HttpRequest.html#securitychecks">security checks</a>. |
|
413 * |
375 * @param <U> a type representing the aggregated results |
414 * @param <U> a type representing the aggregated results |
376 * @param <T> a type representing all of the response bodies |
415 * @param <T> a type representing all of the response bodies |
377 * @param req the request |
416 * @param req the request |
378 * @param multiProcessor the MultiProcessor for the request |
417 * @param multiSubscriber the multiSubscriber for the request |
379 * @return a {@code CompletableFuture<U>} |
418 * @return a {@code CompletableFuture<U>} |
380 */ |
419 */ |
381 public abstract <U, T> CompletableFuture<U> |
420 public abstract <U, T> CompletableFuture<U> |
382 sendAsync(HttpRequest req, HttpResponse.MultiProcessor<U, T> multiProcessor); |
421 sendAsync(HttpRequest req, HttpResponse.MultiSubscriber<U, T> multiSubscriber); |
383 |
422 |
384 /** |
423 /** |
385 * Creates a builder of {@link WebSocket} instances connected to the given |
424 * Creates a builder of {@link WebSocket} instances connected to the given |
386 * URI and receiving events and messages with the given {@code Listener}. |
425 * URI and receiving events and messages with the given {@code Listener}. |
387 * |
426 * |