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