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