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