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