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 }