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