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