1 //
2 // ========================================================================
3 // Copyright (c) 1995-2016 Mort Bay Consulting Pty. Ltd.
4 // ------------------------------------------------------------------------
5 // All rights reserved. This program and the accompanying materials
6 // are made available under the terms of the Eclipse Public License v1.0
7 // and Apache License v2.0 which accompanies this distribution.
8 //
9 // The Eclipse Public License is available at
10 // http://www.eclipse.org/legal/epl-v10.html
11 //
12 // The Apache License v2.0 is available at
13 // http://www.opensource.org/licenses/apache2.0.php
14 //
15 // You may elect to redistribute this code under either of these licenses.
16 // ========================================================================
17 //
18
19 package org.eclipse.jetty.client.api;
20
21 import java.io.IOException;
22 import java.net.HttpCookie;
23 import java.net.URI;
24 import java.nio.ByteBuffer;
25 import java.nio.file.Path;
26 import java.util.EventListener;
27 import java.util.List;
28 import java.util.Map;
29 import java.util.concurrent.ExecutionException;
30 import java.util.concurrent.TimeUnit;
31 import java.util.concurrent.TimeoutException;
32
33 import org.eclipse.jetty.http.HttpFields;
34 import org.eclipse.jetty.http.HttpHeader;
35 import org.eclipse.jetty.http.HttpMethod;
36 import org.eclipse.jetty.http.HttpVersion;
37 import org.eclipse.jetty.util.Fields;
38
39 /**
40 * <p>{@link Request} represents a HTTP request, and offers a fluent interface to customize
41 * various attributes such as the path, the headers, the content, etc.</p>
42 * <p>You can create {@link Request} objects via {@link HttpClient#newRequest(String)} and
43 * you can send them using either {@link #send()} for a blocking semantic, or
44 * {@link #send(Response.CompleteListener)} for an asynchronous semantic.</p>
45 *
46 * @see Response
47 */
48 public interface Request
49 {
50 /**
51 * @return the scheme of this request, such as "http" or "https"
52 */
53 String getScheme();
54
55 /**
56 * @param scheme the scheme of this request, such as "http" or "https"
57 * @return this request object
58 */
59 Request scheme(String scheme);
60
61 /**
62 * @return the host of this request, such as "127.0.0.1" or "google.com"
63 */
64 String getHost();
65
66 /**
67 * @return the port of this request such as 80 or 443
68 */
69 int getPort();
70
71 /**
72 * @return the method of this request, such as GET or POST, as a String
73 */
74 String getMethod();
75
76 /**
77 * @param method the method of this request, such as GET or POST
78 * @return this request object
79 */
80 Request method(HttpMethod method);
81
82 /**
83 * @param method the method of this request, such as GET or POST
84 * @return this request object
85 */
86 Request method(String method);
87
88 /**
89 * @return the path of this request, such as "/" or "/path" - without the query
90 * @see #getQuery()
91 */
92 String getPath();
93
94 /**
95 * Specifies the path - and possibly the query - of this request.
96 * If the query part is specified, parameter values must be properly
97 * {@link URLEncoder#encode(String, String) UTF-8 URL encoded}.
98 * For example, if the value for parameter "currency" is the euro symbol € then the
99 * query string for this parameter must be "currency=%E2%82%AC".
100 * For transparent encoding of parameter values, use {@link #param(String, String)}.
101 *
102 * @param path the path of this request, such as "/" or "/path?param=1"
103 * @return this request object
104 */
105 Request path(String path);
106
107 /**
108 * @return the query string of this request such as "param=1"
109 * @see #getPath()
110 * @see #getParams()
111 */
112 String getQuery();
113
114 /**
115 * @return the full URI of this request such as "http://host:port/path?param=1"
116 */
117 URI getURI();
118
119 /**
120 * @return the HTTP version of this request, such as "HTTP/1.1"
121 */
122 HttpVersion getVersion();
123
124 /**
125 * @param version the HTTP version of this request, such as "HTTP/1.1"
126 * @return this request object
127 */
128 Request version(HttpVersion version);
129
130 /**
131 * @return the query parameters of this request
132 */
133 Fields getParams();
134
135 /**
136 * Adds a query parameter with the given name and value.
137 * The value is {@link URLEncoder#encode(String, String) UTF-8 URL encoded}.
138 *
139 * @param name the name of the query parameter
140 * @param value the value of the query parameter
141 * @return this request object
142 */
143 Request param(String name, String value);
144
145 /**
146 * @return the headers of this request
147 */
148 HttpFields getHeaders();
149
150 /**
151 * @param name the name of the header
152 * @param value the value of the header
153 * @return this request object
154 * @see #header(HttpHeader, String)
155 */
156 Request header(String name, String value);
157
158 /**
159 * <p>Adds the given {@code value} to the specified {@code header}.</p>
160 * <p>Multiple calls with the same parameters will add multiple values;
161 * use the value {@code null} to remove the header completely.</p>
162 *
163 * @param header the header name
164 * @param value the value of the header
165 * @return this request object
166 */
167 Request header(HttpHeader header, String value);
168
169 /**
170 * @return the cookies associated with this request
171 */
172 List<HttpCookie> getCookies();
173
174 /**
175 * @param cookie a cookie for this request
176 * @return this request object
177 */
178 Request cookie(HttpCookie cookie);
179
180 /**
181 * @param name the name of the attribute
182 * @param value the value of the attribute
183 * @return this request object
184 */
185 Request attribute(String name, Object value);
186
187 /**
188 * @return the attributes of this request
189 */
190 Map<String, Object> getAttributes();
191
192 /**
193 * @return the content provider of this request
194 */
195 ContentProvider getContent();
196
197 /**
198 * @param content the content provider of this request
199 * @return this request object
200 */
201 Request content(ContentProvider content);
202
203 /**
204 * @param content the content provider of this request
205 * @return this request object
206 */
207 Request content(ContentProvider content, String contentType);
208
209 /**
210 * Shortcut method to specify a file as a content for this request, with the default content type of
211 * "application/octect-stream".
212 *
213 * @param file the file to upload
214 * @return this request object
215 * @throws IOException if the file does not exist or cannot be read
216 */
217 Request file(Path file) throws IOException;
218
219 /**
220 * Shortcut method to specify a file as a content for this request, with the given content type.
221 *
222 * @param file the file to upload
223 * @param contentType the content type of the file
224 * @return this request object
225 * @throws IOException if the file does not exist or cannot be read
226 */
227 Request file(Path file, String contentType) throws IOException;
228
229 /**
230 * @return the user agent for this request
231 */
232 String getAgent();
233
234 /**
235 * @param agent the user agent for this request (corresponds to the {@code User-Agent} header)
236 * @return this request object
237 */
238 Request agent(String agent);
239
240 /**
241 * @param accepts the media types that are acceptable in the response, such as
242 * "text/plain;q=0.5" or "text/html" (corresponds to the {@code Accept} header)
243 * @return this request object
244 */
245 Request accept(String... accepts);
246
247 /**
248 * @return the idle timeout for this request, in milliseconds
249 */
250 long getIdleTimeout();
251
252 /**
253 * @param timeout the idle timeout for this request
254 * @param unit the idle timeout unit
255 * @return this request object
256 */
257 Request idleTimeout(long timeout, TimeUnit unit);
258
259 /**
260 * @return the total timeout for this request, in milliseconds
261 */
262 long getTimeout();
263
264 /**
265 * @param timeout the total timeout for the request/response conversation
266 * @param unit the timeout unit
267 * @return this request object
268 */
269 Request timeout(long timeout, TimeUnit unit);
270
271 /**
272 * @return whether this request follows redirects
273 */
274 boolean isFollowRedirects();
275
276 /**
277 * @param follow whether this request follows redirects
278 * @return this request object
279 */
280 Request followRedirects(boolean follow);
281
282 /**
283 * @param listenerClass the class of the listener, or null for all listeners classes
284 * @return the listeners for request events of the given class
285 */
286 <T extends RequestListener> List<T> getRequestListeners(Class<T> listenerClass);
287
288 /**
289 * @param listener a listener for request events
290 * @return this request object
291 */
292 Request listener(Listener listener);
293
294 /**
295 * @param listener a listener for request queued event
296 * @return this request object
297 */
298 Request onRequestQueued(QueuedListener listener);
299
300 /**
301 * @param listener a listener for request begin event
302 * @return this request object
303 */
304 Request onRequestBegin(BeginListener listener);
305
306 /**
307 * @param listener a listener for request headers event
308 * @return this request object
309 */
310 Request onRequestHeaders(HeadersListener listener);
311
312 /**
313 * @param listener a listener for request commit event
314 * @return this request object
315 */
316 Request onRequestCommit(CommitListener listener);
317
318 /**
319 * @param listener a listener for request content events
320 * @return this request object
321 */
322 Request onRequestContent(ContentListener listener);
323
324 /**
325 * @param listener a listener for request success event
326 * @return this request object
327 */
328 Request onRequestSuccess(SuccessListener listener);
329
330 /**
331 * @param listener a listener for request failure event
332 * @return this request object
333 */
334 Request onRequestFailure(FailureListener listener);
335
336 /**
337 * @param listener a listener for response begin event
338 * @return this request object
339 */
340 Request onResponseBegin(Response.BeginListener listener);
341
342 /**
343 * @param listener a listener for response header event
344 * @return this request object
345 */
346 Request onResponseHeader(Response.HeaderListener listener);
347
348 /**
349 * @param listener a listener for response headers event
350 * @return this request object
351 */
352 Request onResponseHeaders(Response.HeadersListener listener);
353
354 /**
355 * @param listener a consuming listener for response content events
356 * @return this request object
357 */
358 Request onResponseContent(Response.ContentListener listener);
359
360 /**
361 * @param listener an asynchronous listener for response content events
362 * @return this request object
363 */
364 Request onResponseContentAsync(Response.AsyncContentListener listener);
365
366 /**
367 * @param listener a listener for response success event
368 * @return this request object
369 */
370 Request onResponseSuccess(Response.SuccessListener listener);
371
372 /**
373 * @param listener a listener for response failure event
374 * @return this request object
375 */
376 Request onResponseFailure(Response.FailureListener listener);
377
378 /**
379 * @param listener a listener for complete event
380 * @return this request object
381 */
382 Request onComplete(Response.CompleteListener listener);
383
384 /**
385 * Sends this request and returns the response.
386 * <p />
387 * This method should be used when a simple blocking semantic is needed, and when it is known
388 * that the response content can be buffered without exceeding memory constraints.
389 * <p />
390 * For example, this method is not appropriate to download big files from a server; consider using
391 * {@link #send(Response.CompleteListener)} instead, passing your own {@link Response.Listener} or a utility
392 * listener such as {@link InputStreamResponseListener}.
393 * <p />
394 * The method returns when the {@link Response.CompleteListener complete event} is fired.
395 *
396 * @return a {@link ContentResponse} for this request
397 * @see Response.CompleteListener#onComplete(Result)
398 */
399 ContentResponse send() throws InterruptedException, TimeoutException, ExecutionException;
400
401 /**
402 * <p>Sends this request and asynchronously notifies the given listener for response events.</p>
403 * <p>This method should be used when the application needs to be notified of the various response events
404 * as they happen, or when the application needs to efficiently manage the response content.</p>
405 * <p>The listener passed to this method may implement not only {@link Response.CompleteListener}
406 * but also other response listener interfaces, and all the events implemented will be notified.
407 * This allows application code to write a single listener class to handle all relevant events.</p>
408 *
409 * @param listener the listener that receives response events
410 */
411 void send(Response.CompleteListener listener);
412
413 /**
414 * Attempts to abort the send of this request.
415 *
416 * @param cause the abort cause, must not be null
417 * @return whether the abort succeeded
418 */
419 boolean abort(Throwable cause);
420
421 /**
422 * @return the abort cause passed to {@link #abort(Throwable)},
423 * or null if this request has not been aborted
424 */
425 Throwable getAbortCause();
426
427 /**
428 * Common, empty, super-interface for request listeners.
429 */
430 public interface RequestListener extends EventListener
431 {
432 }
433
434 /**
435 * Listener for the request queued event.
436 */
437 public interface QueuedListener extends RequestListener
438 {
439 /**
440 * Callback method invoked when the request is queued, waiting to be sent
441 *
442 * @param request the request being queued
443 */
444 public void onQueued(Request request);
445 }
446
447 /**
448 * Listener for the request begin event.
449 */
450 public interface BeginListener extends RequestListener
451 {
452 /**
453 * Callback method invoked when the request begins being processed in order to be sent.
454 * This is the last opportunity to modify the request.
455 *
456 * @param request the request that begins being processed
457 */
458 public void onBegin(Request request);
459 }
460
461 /**
462 * Listener for the request headers event.
463 */
464 public interface HeadersListener extends RequestListener
465 {
466 /**
467 * Callback method invoked when the request headers (and perhaps small content) are ready to be sent.
468 * The request has been converted into bytes, but not yet sent to the server, and further modifications
469 * to the request may have no effect.
470 * @param request the request that is about to be committed
471 */
472 public void onHeaders(Request request);
473 }
474
475 /**
476 * Listener for the request committed event.
477 */
478 public interface CommitListener extends RequestListener
479 {
480 /**
481 * Callback method invoked when the request headers (and perhaps small content) have been sent.
482 * The request is now committed, and in transit to the server, and further modifications to the
483 * request may have no effect.
484 * @param request the request that has been committed
485 */
486 public void onCommit(Request request);
487 }
488
489 /**
490 * Listener for the request content event.
491 */
492 public interface ContentListener extends RequestListener
493 {
494 /**
495 * Callback method invoked when a chunk of request content has been sent successfully.
496 * Changes to bytes in the given buffer have no effect, as the content has already been sent.
497 * @param request the request that has been committed
498 */
499 public void onContent(Request request, ByteBuffer content);
500 }
501
502 /**
503 * Listener for the request succeeded event.
504 */
505 public interface SuccessListener extends RequestListener
506 {
507 /**
508 * Callback method invoked when the request has been successfully sent.
509 *
510 * @param request the request sent
511 */
512 public void onSuccess(Request request);
513 }
514
515 /**
516 * Listener for the request failed event.
517 */
518 public interface FailureListener extends RequestListener
519 {
520 /**
521 * Callback method invoked when the request has failed to be sent
522 * @param request the request that failed
523 * @param failure the failure
524 */
525 public void onFailure(Request request, Throwable failure);
526 }
527
528 /**
529 * Listener for all request events.
530 */
531 public interface Listener extends QueuedListener, BeginListener, HeadersListener, CommitListener, ContentListener, SuccessListener, FailureListener
532 {
533 /**
534 * An empty implementation of {@link Listener}
535 */
536 public static class Adapter implements Listener
537 {
538 @Override
539 public void onQueued(Request request)
540 {
541 }
542
543 @Override
544 public void onBegin(Request request)
545 {
546 }
547
548 @Override
549 public void onHeaders(Request request)
550 {
551 }
552
553 @Override
554 public void onCommit(Request request)
555 {
556 }
557
558 @Override
559 public void onContent(Request request, ByteBuffer content)
560 {
561 }
562
563 @Override
564 public void onSuccess(Request request)
565 {
566 }
567
568 @Override
569 public void onFailure(Request request, Throwable failure)
570 {
571 }
572 }
573 }
574 }