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.nio.ByteBuffer;
22 import java.util.EventListener;
23 import java.util.List;
24
25 import org.eclipse.jetty.http.HttpField;
26 import org.eclipse.jetty.http.HttpFields;
27 import org.eclipse.jetty.http.HttpVersion;
28 import org.eclipse.jetty.util.Callback;
29
30 /**
31 * <p>{@link Response} represents a HTTP response and offers methods to retrieve status code, HTTP version
32 * and headers.</p>
33 * <p>{@link Response} objects are passed as parameters to {@link Response.Listener} callbacks, or as
34 * future result of {@link Request#send()}.</p>
35 * <p>{@link Response} objects do not contain getters for the response content, because it may be too large
36 * to fit into memory.
37 * The response content should be retrieved via {@link Response.Listener#onContent(Response, ByteBuffer) content
38 * events}, or via utility classes such as {@link BufferingResponseListener}.</p>
39 */
40 public interface Response
41 {
42 /**
43 * @return the request associated with this response
44 */
45 Request getRequest();
46
47 /**
48 * @return the response listener passed to {@link Request#send(CompleteListener)}
49 */
50 <T extends ResponseListener> List<T> getListeners(Class<T> listenerClass);
51
52 /**
53 * @return the HTTP version of this response, such as "HTTP/1.1"
54 */
55 HttpVersion getVersion();
56
57 /**
58 * @return the HTTP status code of this response, such as 200 or 404
59 */
60 int getStatus();
61
62 /**
63 * @return the HTTP reason associated to the {@link #getStatus}
64 */
65 String getReason();
66
67 /**
68 * @return the headers of this response
69 */
70 HttpFields getHeaders();
71
72 /**
73 * Attempts to abort the receive of this response.
74 *
75 * @param cause the abort cause, must not be null
76 * @return whether the abort succeeded
77 */
78 boolean abort(Throwable cause);
79
80 /**
81 * Common, empty, super-interface for response listeners
82 */
83 public interface ResponseListener extends EventListener
84 {
85 }
86
87 /**
88 * Listener for the response begin event.
89 */
90 public interface BeginListener extends ResponseListener
91 {
92 /**
93 * Callback method invoked when the response line containing HTTP version,
94 * HTTP status code and reason has been received and parsed.
95 * <p />
96 * This method is the best approximation to detect when the first bytes of the response arrived to the client.
97 *
98 * @param response the response containing the response line data
99 */
100 public void onBegin(Response response);
101 }
102
103 /**
104 * Listener for a response header event.
105 */
106 public interface HeaderListener extends ResponseListener
107 {
108 /**
109 * Callback method invoked when a response header has been received,
110 * returning whether the header should be processed or not.
111 *
112 * @param response the response containing the response line data and the headers so far
113 * @param field the header received
114 * @return true to process the header, false to skip processing of the header
115 */
116 public boolean onHeader(Response response, HttpField field);
117 }
118
119 /**
120 * Listener for the response headers event.
121 */
122 public interface HeadersListener extends ResponseListener
123 {
124 /**
125 * Callback method invoked when the response headers have been received and parsed.
126 *
127 * @param response the response containing the response line data and the headers
128 */
129 public void onHeaders(Response response);
130 }
131
132 /**
133 * Listener for the response content events.
134 */
135 public interface ContentListener extends ResponseListener
136 {
137 /**
138 * Callback method invoked when the response content has been received.
139 * This method may be invoked multiple times, and the {@code content} buffer must be consumed
140 * before returning from this method.
141 *
142 * @param response the response containing the response line data and the headers
143 * @param content the content bytes received
144 */
145 public void onContent(Response response, ByteBuffer content);
146 }
147
148 public interface AsyncContentListener extends ResponseListener
149 {
150 /**
151 * Callback method invoked asynchronously when the response content has been received.
152 *
153 * @param response the response containing the response line data and the headers
154 * @param content the content bytes received
155 * @param callback the callback to call when the content is consumed.
156 */
157 public void onContent(Response response, ByteBuffer content, Callback callback);
158 }
159
160 /**
161 * Listener for the response succeeded event.
162 */
163 public interface SuccessListener extends ResponseListener
164 {
165 /**
166 * Callback method invoked when the whole response has been successfully received.
167 *
168 * @param response the response containing the response line data and the headers
169 */
170 public void onSuccess(Response response);
171 }
172
173 /**
174 * Listener for the response failure event.
175 */
176 public interface FailureListener extends ResponseListener
177 {
178 /**
179 * Callback method invoked when the response has failed in the process of being received
180 *
181 * @param response the response containing data up to the point the failure happened
182 * @param failure the failure happened
183 */
184 public void onFailure(Response response, Throwable failure);
185 }
186
187 /**
188 * Listener for the request and response completed event.
189 */
190 public interface CompleteListener extends ResponseListener
191 {
192 /**
193 * Callback method invoked when the request <em><b>and</b></em> the response have been processed,
194 * either successfully or not.
195 * <p/>
196 * The {@code result} parameter contains the request, the response, and eventual failures.
197 * <p/>
198 * Requests may complete <em>after</em> response, for example in case of big uploads that are
199 * discarded or read asynchronously by the server.
200 * This method is always invoked <em>after</em> {@link SuccessListener#onSuccess(Response)} or
201 * {@link FailureListener#onFailure(Response, Throwable)}, and only when request indicates that
202 * it is completed.
203 *
204 * @param result the result of the request / response exchange
205 */
206 public void onComplete(Result result);
207 }
208
209 /**
210 * Listener for all response events.
211 */
212 public interface Listener extends BeginListener, HeaderListener, HeadersListener, ContentListener, AsyncContentListener, SuccessListener, FailureListener, CompleteListener
213 {
214 /**
215 * An empty implementation of {@link Listener}
216 */
217 public static class Adapter implements Listener
218 {
219 @Override
220 public void onBegin(Response response)
221 {
222 }
223
224 @Override
225 public boolean onHeader(Response response, HttpField field)
226 {
227 return true;
228 }
229
230 @Override
231 public void onHeaders(Response response)
232 {
233 }
234
235 @Override
236 public void onContent(Response response, ByteBuffer content)
237 {
238 }
239
240 @Override
241 public void onContent(Response response, ByteBuffer content, Callback callback)
242 {
243 try
244 {
245 onContent(response, content);
246 callback.succeeded();
247 }
248 catch (Exception x)
249 {
250 callback.failed(x);
251 }
252 }
253
254 @Override
255 public void onSuccess(Response response)
256 {
257 }
258
259 @Override
260 public void onFailure(Response response, Throwable failure)
261 {
262 }
263
264 @Override
265 public void onComplete(Result result)
266 {
267 }
268 }
269 }
270 }