120 * to authentication, redirection and cookie management may be managed by |
120 * to authentication, redirection and cookie management may be managed by |
121 * specific APIs rather than through directly user set headers. |
121 * specific APIs rather than through directly user set headers. |
122 * |
122 * |
123 * @since 11 |
123 * @since 11 |
124 */ |
124 */ |
125 public abstract static class Builder { |
125 public interface Builder { |
126 |
|
127 /** |
|
128 * Creates a Builder. |
|
129 */ |
|
130 protected Builder() {} |
|
131 |
126 |
132 /** |
127 /** |
133 * Sets this {@code HttpRequest}'s request {@code URI}. |
128 * Sets this {@code HttpRequest}'s request {@code URI}. |
134 * |
129 * |
135 * @param uri the request URI |
130 * @param uri the request URI |
136 * @return this request builder |
131 * @return this request builder |
137 * @throws IllegalArgumentException if the {@code URI} scheme is not |
132 * @throws IllegalArgumentException if the {@code URI} scheme is not |
138 * supported |
133 * supported |
139 */ |
134 */ |
140 public abstract Builder uri(URI uri); |
135 public Builder uri(URI uri); |
141 |
136 |
142 /** |
137 /** |
143 * Requests the server to acknowledge the request before sending the |
138 * Requests the server to acknowledge the request before sending the |
144 * body. This is disabled by default. If enabled, the server is |
139 * body. This is disabled by default. If enabled, the server is |
145 * requested to send an error response or a {@code 100 Continue} |
140 * requested to send an error response or a {@code 100 Continue} |
148 * interim response is received. |
143 * interim response is received. |
149 * |
144 * |
150 * @param enable {@code true} if Expect continue to be sent |
145 * @param enable {@code true} if Expect continue to be sent |
151 * @return this request builder |
146 * @return this request builder |
152 */ |
147 */ |
153 public abstract Builder expectContinue(boolean enable); |
148 public Builder expectContinue(boolean enable); |
154 |
149 |
155 /** |
150 /** |
156 * Sets the preferred {@link HttpClient.Version} for this request. |
151 * Sets the preferred {@link HttpClient.Version} for this request. |
157 * |
152 * |
158 * <p> The corresponding {@link HttpResponse} should be checked for the |
153 * <p> The corresponding {@link HttpResponse} should be checked for the |
161 * {@link HttpClient}. |
156 * {@link HttpClient}. |
162 * |
157 * |
163 * @param version the HTTP protocol version requested |
158 * @param version the HTTP protocol version requested |
164 * @return this request builder |
159 * @return this request builder |
165 */ |
160 */ |
166 public abstract Builder version(HttpClient.Version version); |
161 public Builder version(HttpClient.Version version); |
167 |
162 |
168 /** |
163 /** |
169 * Adds the given name value pair to the set of headers for this request. |
164 * Adds the given name value pair to the set of headers for this request. |
170 * The given value is added to the list of values for that name. |
165 * The given value is added to the list of values for that name. |
171 * |
166 * |
183 * @throws IllegalArgumentException if the header name or value is not |
178 * @throws IllegalArgumentException if the header name or value is not |
184 * valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
179 * valid, see <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
185 * RFC 7230 section-3.2</a>, or the header name or value is restricted |
180 * RFC 7230 section-3.2</a>, or the header name or value is restricted |
186 * by the implementation. |
181 * by the implementation. |
187 */ |
182 */ |
188 public abstract Builder header(String name, String value); |
183 public Builder header(String name, String value); |
189 |
184 |
190 /** |
185 /** |
191 * Adds the given name value pairs to the set of headers for this |
186 * Adds the given name value pairs to the set of headers for this |
192 * request. The supplied {@code String} instances must alternate as |
187 * request. The supplied {@code String} instances must alternate as |
193 * header names and header values. |
188 * header names and header values. |
201 * <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
196 * <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
202 * RFC 7230 section-3.2</a>, or a header name or value is |
197 * RFC 7230 section-3.2</a>, or a header name or value is |
203 * {@linkplain #header(String, String) restricted} by the |
198 * {@linkplain #header(String, String) restricted} by the |
204 * implementation. |
199 * implementation. |
205 */ |
200 */ |
206 public abstract Builder headers(String... headers); |
201 public Builder headers(String... headers); |
207 |
202 |
208 /** |
203 /** |
209 * Sets a timeout for this request. If the response is not received |
204 * Sets a timeout for this request. If the response is not received |
210 * within the specified timeout then a {@link HttpTimeoutException} is |
205 * within the specified timeout then a {@link HttpTimeoutException} is |
211 * thrown from {@link HttpClient#send(java.net.http.HttpRequest, |
206 * thrown from {@link HttpClient#send(java.net.http.HttpRequest, |
233 * see <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
228 * see <a href="https://tools.ietf.org/html/rfc7230#section-3.2"> |
234 * RFC 7230 section-3.2</a>, or the header name or value is |
229 * RFC 7230 section-3.2</a>, or the header name or value is |
235 * {@linkplain #header(String, String) restricted} by the |
230 * {@linkplain #header(String, String) restricted} by the |
236 * implementation. |
231 * implementation. |
237 */ |
232 */ |
238 public abstract Builder setHeader(String name, String value); |
233 public Builder setHeader(String name, String value); |
239 |
234 |
240 /** |
235 /** |
241 * Sets the request method of this builder to GET. |
236 * Sets the request method of this builder to GET. |
242 * This is the default. |
237 * This is the default. |
243 * |
238 * |
244 * @return a {@code HttpRequest} |
239 * @return a {@code HttpRequest} |
245 */ |
240 */ |
246 public abstract Builder GET(); |
241 public Builder GET(); |
247 |
242 |
248 /** |
243 /** |
249 * Sets the request method of this builder to POST and sets its |
244 * Sets the request method of this builder to POST and sets its |
250 * request body publisher to the given value. |
245 * request body publisher to the given value. |
251 * |
246 * |
252 * @param bodyPublisher the body publisher |
247 * @param bodyPublisher the body publisher |
253 * |
248 * |
254 * @return a {@code HttpRequest} |
249 * @return a {@code HttpRequest} |
255 */ |
250 */ |
256 public abstract Builder POST(BodyPublisher bodyPublisher); |
251 public Builder POST(BodyPublisher bodyPublisher); |
257 |
252 |
258 /** |
253 /** |
259 * Sets the request method of this builder to PUT and sets its |
254 * Sets the request method of this builder to PUT and sets its |
260 * request body publisher to the given value. |
255 * request body publisher to the given value. |
261 * |
256 * |
262 * @param bodyPublisher the body publisher |
257 * @param bodyPublisher the body publisher |
263 * |
258 * |
264 * @return a {@code HttpRequest} |
259 * @return a {@code HttpRequest} |
265 */ |
260 */ |
266 public abstract Builder PUT(BodyPublisher bodyPublisher); |
261 public Builder PUT(BodyPublisher bodyPublisher); |
267 |
262 |
268 /** |
263 /** |
269 * Sets the request method of this builder to DELETE and sets its |
264 * Sets the request method of this builder to DELETE and sets its |
270 * request body publisher to the given value. |
265 * request body publisher to the given value. |
271 * |
266 * |
272 * @param bodyPublisher the body publisher |
267 * @param bodyPublisher the body publisher |
273 * |
268 * |
274 * @return a {@code HttpRequest} |
269 * @return a {@code HttpRequest} |
275 */ |
270 */ |
276 |
271 |
277 public abstract Builder DELETE(BodyPublisher bodyPublisher); |
272 public Builder DELETE(BodyPublisher bodyPublisher); |
278 |
273 |
279 /** |
274 /** |
280 * Sets the request method and request body of this builder to the |
275 * Sets the request method and request body of this builder to the |
281 * given values. |
276 * given values. |
282 * |
277 * |
289 * @param method the method to use |
284 * @param method the method to use |
290 * @param bodyPublisher the body publisher |
285 * @param bodyPublisher the body publisher |
291 * @return a {@code HttpRequest} |
286 * @return a {@code HttpRequest} |
292 * @throws IllegalArgumentException if the method is restricted |
287 * @throws IllegalArgumentException if the method is restricted |
293 */ |
288 */ |
294 public abstract Builder method(String method, BodyPublisher bodyPublisher); |
289 public Builder method(String method, BodyPublisher bodyPublisher); |
295 |
290 |
296 /** |
291 /** |
297 * Builds and returns a {@link HttpRequest}. |
292 * Builds and returns a {@link HttpRequest}. |
298 * |
293 * |
299 * @return the request |
294 * @return the request |
300 * @throws IllegalStateException if a URI has not been set |
295 * @throws IllegalStateException if a URI has not been set |
301 */ |
296 */ |
302 public abstract HttpRequest build(); |
297 public HttpRequest build(); |
303 |
298 |
304 /** |
299 /** |
305 * Returns an exact duplicate copy of this {@code Builder} based on |
300 * Returns an exact duplicate copy of this {@code Builder} based on |
306 * current state. The new builder can then be modified independently of |
301 * current state. The new builder can then be modified independently of |
307 * this builder. |
302 * this builder. |
308 * |
303 * |
309 * @return an exact copy of this Builder |
304 * @return an exact copy of this Builder |
310 */ |
305 */ |
311 public abstract Builder copy(); |
306 public Builder copy(); |
312 } |
307 } |
313 |
308 |
314 /** |
309 /** |
315 * Creates an {@code HttpRequest} builder with the given URI. |
310 * Creates an {@code HttpRequest} builder with the given URI. |
316 * |
311 * |