1 //
2 // ========================================================================
3 // Copyright (c) 1995-2012 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.nio.file.Path;
23 import java.util.EventListener;
24 import java.util.List;
25 import java.util.Map;
26 import java.util.concurrent.Future;
27
28 import org.eclipse.jetty.client.HttpClient;
29 import org.eclipse.jetty.http.HttpFields;
30 import org.eclipse.jetty.http.HttpMethod;
31 import org.eclipse.jetty.http.HttpVersion;
32 import org.eclipse.jetty.util.Fields;
33
34 /**
35 * <p>{@link Request} represents a HTTP request, and offers a fluent interface to customize
36 * various attributes such as the path, the headers, the content, etc.</p>
37 * <p>You can create {@link Request} objects via {@link HttpClient#newRequest(String)} and
38 * you can send them using either {@link #send()} for a blocking semantic, or
39 * {@link #send(Response.Listener)} for an asynchronous semantic.</p>
40 *
41 * @see Response
42 */
43 public interface Request
44 {
45 /**
46 * @return the conversation id
47 */
48 long getConversationID();
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
73 */
74 HttpMethod 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 * @return the path of this request, such as "/"
84 */
85 String getPath();
86
87 /**
88 * @param path the path of this request, such as "/"
89 * @return this request object
90 */
91 Request path(String path);
92
93 /**
94 * @return the full URI of this request such as "http://host:port/path"
95 */
96 String getURI();
97
98 /**
99 * @return the HTTP version of this request, such as "HTTP/1.1"
100 */
101 HttpVersion getVersion();
102
103 /**
104 * @param version the HTTP version of this request, such as "HTTP/1.1"
105 * @return this request object
106 */
107 Request version(HttpVersion version);
108
109 /**
110 * @return the query parameters of this request
111 */
112 Fields getParams();
113
114 /**
115 * @param name the name of the query parameter
116 * @param value the value of the query parameter
117 * @return this request object
118 */
119 Request param(String name, String value);
120
121 /**
122 * @return the headers of this request
123 */
124 HttpFields getHeaders();
125
126 /**
127 * @param name the name of the header
128 * @param value the value of the header
129 * @return this request object
130 */
131 Request header(String name, String value);
132
133 /**
134 * @param name the name of the attribute
135 * @param value the value of the attribute
136 * @return this request object
137 */
138 Request attribute(String name, Object value);
139
140 /**
141 * @return the attributes of this request
142 */
143 Map<String, Object> getAttributes();
144
145 /**
146 * @return the content provider of this request
147 */
148 ContentProvider getContent();
149
150 /**
151 * @param content the content provider of this request
152 * @return this request object
153 */
154 Request content(ContentProvider content);
155
156 /**
157 * Shortcut method to specify a file as a content for this request, with the default content type of
158 * "application/octect-stream".
159 *
160 * @param file the file to upload
161 * @return this request object
162 * @throws IOException if the file does not exist or cannot be read
163 */
164 Request file(Path file) throws IOException;
165
166 /**
167 * Shortcut method to specify a file as a content for this request, with the given content type.
168 *
169 * @param file the file to upload
170 * @param contentType the content type of the file
171 * @return this request object
172 * @throws IOException if the file does not exist or cannot be read
173 */
174 Request file(Path file, String contentType) throws IOException;
175
176 /**
177 * @return the user agent for this request
178 */
179 String getAgent();
180
181 /**
182 * @param agent the user agent for this request
183 * @return this request object
184 */
185 Request agent(String agent);
186
187 /**
188 * @return the idle timeout for this request
189 */
190 long getIdleTimeout();
191
192 /**
193 * @param timeout the idle timeout for this request
194 * @return this request object
195 */
196 Request idleTimeout(long timeout);
197
198 /**
199 * @return whether this request follows redirects
200 */
201 boolean isFollowRedirects();
202
203 /**
204 * @param follow whether this request follows redirects
205 * @return this request object
206 */
207 Request followRedirects(boolean follow);
208
209 /**
210 * @param listenerClass the class of the listener, or null for all listeners classes
211 * @return the listeners for request events of the given class
212 */
213 <T extends RequestListener> List<T> getRequestListeners(Class<T> listenerClass);
214
215 /**
216 * @param listener a listener for request events
217 * @return this request object
218 */
219 Request listener(Listener listener);
220
221 /**
222 * @param listener a listener for request queued event
223 * @return this request object
224 */
225 Request onRequestQueued(QueuedListener listener);
226
227 /**
228 * @param listener a listener for request begin event
229 * @return this request object
230 */
231 Request onRequestBegin(BeginListener listener);
232
233 /**
234 * @param listener a listener for request headers event
235 * @return this request object
236 */
237 Request onRequestHeaders(HeadersListener listener);
238
239 /**
240 * @param listener a listener for request success event
241 * @return this request object
242 */
243 Request onRequestSuccess(SuccessListener listener);
244
245 /**
246 * @param listener a listener for request failure event
247 * @return this request object
248 */
249 Request onRequestFailure(FailureListener listener);
250
251 /**
252 * @param listener a listener for response begin event
253 * @return this request object
254 */
255 Request onResponseBegin(Response.BeginListener listener);
256
257 /**
258 * @param listener a listener for response headers event
259 * @return this request object
260 */
261 Request onResponseHeaders(Response.HeadersListener listener);
262
263 /**
264 * @param listener a listener for response content events
265 * @return this request object
266 */
267 Request onResponseContent(Response.ContentListener listener);
268
269 /**
270 * @param listener a listener for response success event
271 * @return this request object
272 */
273 Request onResponseSuccess(Response.SuccessListener listener);
274
275 /**
276 * @param listener a listener for response failure event
277 * @return this request object
278 */
279 Request onResponseFailure(Response.FailureListener listener);
280
281 /**
282 * Sends this request and returns a {@link Future} that can be used to wait for the
283 * request and the response to be completed (either with a success or a failure).
284 * <p />
285 * This method should be used when a simple blocking semantic is needed, and when it is known
286 * that the response content can be buffered without exceeding memory constraints.
287 * For example, this method is not appropriate to download big files from a server; consider using
288 * {@link #send(Response.Listener)} instead, passing your own {@link Response.Listener} or a utility
289 * listener such as {@link InputStreamResponseListener}.
290 * <p />
291 * The future will return when {@link Response.Listener#onComplete(Result)} is invoked.
292 *
293 * @return a {@link Future} to wait on for request and response completion
294 * @see Response.Listener#onComplete(Result)
295 */
296 Future<ContentResponse> send();
297
298 /**
299 * Sends this request and asynchronously notifies the given listener for response events.
300 * <p />
301 * This method should be used when the application needs to be notified of the various response events
302 * as they happen, or when the application needs to efficiently manage the response content.
303 *
304 * @param listener the listener that receives response events
305 */
306 void send(Response.CompleteListener listener);
307
308 /**
309 * Attempts to abort the send of this request.
310 *
311 * @param cause the abort cause, must not be null
312 * @return whether the abort succeeded
313 */
314 boolean abort(Throwable cause);
315
316 /**
317 * @return the abort cause passed to {@link #abort(Throwable)},
318 * or null if this request has not been aborted
319 */
320 Throwable getAbortCause();
321
322 public interface RequestListener extends EventListener
323 {
324 }
325
326 public interface QueuedListener extends RequestListener
327 {
328 /**
329 * Callback method invoked when the request is queued, waiting to be sent
330 *
331 * @param request the request being queued
332 */
333 public void onQueued(Request request);
334 }
335
336 public interface BeginListener extends RequestListener
337 {
338 /**
339 * Callback method invoked when the request begins being processed in order to be sent.
340 * This is the last opportunity to modify the request.
341 *
342 * @param request the request that begins being processed
343 */
344 public void onBegin(Request request);
345 }
346
347 public interface HeadersListener extends RequestListener
348 {
349 /**
350 * Callback method invoked when the request headers (and perhaps small content) have been sent.
351 * The request is now committed, and in transit to the server, and further modifications to the
352 * request may have no effect.
353 * @param request the request that has been committed
354 */
355 public void onHeaders(Request request);
356 }
357
358 public interface SuccessListener extends RequestListener
359 {
360 /**
361 * Callback method invoked when the request has been successfully sent.
362 *
363 * @param request the request sent
364 */
365 public void onSuccess(Request request);
366 }
367
368 public interface FailureListener extends RequestListener
369 {
370 /**
371 * Callback method invoked when the request has failed to be sent
372 * @param request the request that failed
373 * @param failure the failure
374 */
375 public void onFailure(Request request, Throwable failure);
376 }
377
378 /**
379 * Listener for all request events
380 */
381 public interface Listener extends QueuedListener, BeginListener, HeadersListener, SuccessListener, FailureListener
382 {
383 /**
384 * An empty implementation of {@link Listener}
385 */
386 public static class Empty implements Listener
387 {
388 @Override
389 public void onQueued(Request request)
390 {
391 }
392
393 @Override
394 public void onBegin(Request request)
395 {
396 }
397
398 @Override
399 public void onHeaders(Request request)
400 {
401 }
402
403 @Override
404 public void onSuccess(Request request)
405 {
406 }
407
408 @Override
409 public void onFailure(Request request, Throwable failure)
410 {
411 }
412 }
413 }
414 }