OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 1 // Copyright 2014 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 package org.chromium.net; | 5 package org.chromium.net; |
6 | 6 |
7 import android.support.annotation.IntDef; | |
8 import android.util.Log; | |
9 import android.util.Pair; | |
10 | |
11 import java.lang.annotation.Retention; | |
12 import java.lang.annotation.RetentionPolicy; | |
13 import java.nio.ByteBuffer; | 7 import java.nio.ByteBuffer; |
14 import java.util.ArrayList; | |
15 import java.util.Collection; | |
16 import java.util.Collections; | |
17 import java.util.concurrent.Executor; | 8 import java.util.concurrent.Executor; |
18 | 9 |
19 /** | 10 /** |
20 * Controls an HTTP request (GET, PUT, POST etc). | 11 * Controls an HTTP request (GET, PUT, POST etc). |
21 * Created using {@link UrlRequest.Builder}. | 12 * Created by {@link UrlRequest.Builder}, which can be obtained by calling |
22 * Note: All methods must be called on the {@link Executor} passed in during cre
ation. | 13 * {@link CronetEngine#newUrlRequestBuilder}. |
| 14 * Note: All methods must be called on the {@link Executor} passed to |
| 15 * {@link CronetEngine#newUrlRequestBuilder}. |
23 */ | 16 */ |
24 public interface UrlRequest { | 17 public abstract class UrlRequest { |
25 /** | 18 /** |
26 * Builder for {@link UrlRequest}s. Allows configuring requests before const
ructing them | 19 * Builder for {@link UrlRequest}s. Allows configuring requests before const
ructing them |
27 * with {@link Builder#build}. | 20 * with {@link Builder#build}. The builder can be created by calling |
| 21 * {@link CronetEngine#newUrlRequestBuilder}. |
28 */ | 22 */ |
29 public static class Builder { | 23 public abstract static class Builder { |
30 private static final String ACCEPT_ENCODING = "Accept-Encoding"; | |
31 // All fields are temporary storage of UrlRequest configuration to be | |
32 // copied to built UrlRequests. | |
33 | |
34 // CronetEngine to execute request. | |
35 final CronetEngine mCronetEngine; | |
36 // URL to request. | |
37 final String mUrl; | |
38 // Callback to receive progress callbacks. | |
39 final Callback mCallback; | |
40 // Executor to invoke callback on. | |
41 final Executor mExecutor; | |
42 // HTTP method (e.g. GET, POST etc). | |
43 String mMethod; | |
44 // List of request headers, stored as header field name and value pairs. | |
45 final ArrayList<Pair<String, String>> mRequestHeaders = | |
46 new ArrayList<Pair<String, String>>(); | |
47 // Disable the cache for just this request. | |
48 boolean mDisableCache; | |
49 // Disable connection migration for just this request. | |
50 boolean mDisableConnectionMigration; | |
51 // Priority of request. Default is medium. | |
52 @RequestPriority int mPriority = REQUEST_PRIORITY_MEDIUM; | |
53 // Request reporting annotations. Avoid extra object creation if no anno
tations added. | |
54 Collection<Object> mRequestAnnotations = Collections.emptyList(); | |
55 // If request is an upload, this provides the request body data. | |
56 UploadDataProvider mUploadDataProvider; | |
57 // Executor to call upload data provider back on. | |
58 Executor mUploadDataProviderExecutor; | |
59 private boolean mAllowDirectExecutor = false; | |
60 | |
61 /** | |
62 * Creates a builder for {@link UrlRequest} objects. All callbacks for | |
63 * generated {@link UrlRequest} objects will be invoked on | |
64 * {@code executor}'s thread. {@code executor} must not run tasks on the | |
65 * current thread to prevent blocking networking operations and causing | |
66 * exceptions during shutdown. | |
67 * | |
68 * @param url {@link java.net.URL} for the generated requests. | |
69 * @param callback callback object that gets invoked on different events
. | |
70 * @param executor {@link Executor} on which all callbacks will be invok
ed. | |
71 * @param cronetEngine {@link CronetEngine} used to execute this request
. | |
72 */ | |
73 public Builder( | |
74 String url, Callback callback, Executor executor, CronetEngine c
ronetEngine) { | |
75 if (url == null) { | |
76 throw new NullPointerException("URL is required."); | |
77 } | |
78 if (callback == null) { | |
79 throw new NullPointerException("Callback is required."); | |
80 } | |
81 if (executor == null) { | |
82 throw new NullPointerException("Executor is required."); | |
83 } | |
84 if (cronetEngine == null) { | |
85 throw new NullPointerException("CronetEngine is required."); | |
86 } | |
87 mUrl = url; | |
88 mCallback = callback; | |
89 mExecutor = executor; | |
90 mCronetEngine = cronetEngine; | |
91 } | |
92 | |
93 /** | 24 /** |
94 * Sets the HTTP method verb to use for this request. | 25 * Sets the HTTP method verb to use for this request. |
95 * | 26 * |
96 * <p>The default when this method is not called is "GET" if the request
has | 27 * <p>The default when this method is not called is "GET" if the request
has |
97 * no body or "POST" if it does. | 28 * no body or "POST" if it does. |
98 * | 29 * |
99 * @param method "GET", "HEAD", "DELETE", "POST" or "PUT". | 30 * @param method "GET", "HEAD", "DELETE", "POST" or "PUT". |
100 * @return the builder to facilitate chaining. | 31 * @return the builder to facilitate chaining. |
101 */ | 32 */ |
102 public Builder setHttpMethod(String method) { | 33 public abstract Builder setHttpMethod(String method); |
103 if (method == null) { | |
104 throw new NullPointerException("Method is required."); | |
105 } | |
106 mMethod = method; | |
107 return this; | |
108 } | |
109 | 34 |
110 /** | 35 /** |
111 * Adds a request header. | 36 * Adds a request header. |
112 * | 37 * |
113 * @param header header name. | 38 * @param header header name. |
114 * @param value header value. | 39 * @param value header value. |
115 * @return the builder to facilitate chaining. | 40 * @return the builder to facilitate chaining. |
116 */ | 41 */ |
117 public Builder addHeader(String header, String value) { | 42 public abstract Builder addHeader(String header, String value); |
118 if (header == null) { | |
119 throw new NullPointerException("Invalid header name."); | |
120 } | |
121 if (value == null) { | |
122 throw new NullPointerException("Invalid header value."); | |
123 } | |
124 if (ACCEPT_ENCODING.equalsIgnoreCase(header)) { | |
125 Log.w("cronet", | |
126 "It's not necessary to set Accept-Encoding on requests -
cronet will do" | |
127 + " this automatically for you, and setting it y
ourself has no " | |
128 + "effect. See https://crbug.com/581399 for deta
ils.", | |
129 new Exception()); | |
130 return this; | |
131 } | |
132 mRequestHeaders.add(Pair.create(header, value)); | |
133 return this; | |
134 } | |
135 | 43 |
136 /** | 44 /** |
137 * Disables cache for the request. If context is not set up to use cache
, | 45 * Disables cache for the request. If context is not set up to use cache
, |
138 * this call has no effect. | 46 * this call has no effect. |
139 * @return the builder to facilitate chaining. | 47 * @return the builder to facilitate chaining. |
140 */ | 48 */ |
141 public Builder disableCache() { | 49 public abstract Builder disableCache(); |
142 mDisableCache = true; | |
143 return this; | |
144 } | |
145 | |
146 /** | |
147 * Disables connection migration for the request if enabled for | |
148 * the session. | |
149 * @return the builder to facilitate chaining. | |
150 * | |
151 * @hide as experimental. | |
152 */ | |
153 public Builder disableConnectionMigration() { | |
154 mDisableConnectionMigration = true; | |
155 return this; | |
156 } | |
157 | |
158 /** @hide */ | |
159 @IntDef({ | |
160 REQUEST_PRIORITY_IDLE, REQUEST_PRIORITY_LOWEST, REQUEST_PRIORITY
_LOW, | |
161 REQUEST_PRIORITY_MEDIUM, REQUEST_PRIORITY_HIGHEST, | |
162 }) | |
163 @Retention(RetentionPolicy.SOURCE) | |
164 public @interface RequestPriority {} | |
165 | 50 |
166 /** | 51 /** |
167 * Lowest request priority. Passed to {@link #setPriority}. | 52 * Lowest request priority. Passed to {@link #setPriority}. |
168 */ | 53 */ |
169 public static final int REQUEST_PRIORITY_IDLE = 0; | 54 public static final int REQUEST_PRIORITY_IDLE = 0; |
170 /** | 55 /** |
171 * Very low request priority. Passed to {@link #setPriority}. | 56 * Very low request priority. Passed to {@link #setPriority}. |
172 */ | 57 */ |
173 public static final int REQUEST_PRIORITY_LOWEST = 1; | 58 public static final int REQUEST_PRIORITY_LOWEST = 1; |
174 /** | 59 /** |
175 * Low request priority. Passed to {@link #setPriority}. | 60 * Low request priority. Passed to {@link #setPriority}. |
176 */ | 61 */ |
177 public static final int REQUEST_PRIORITY_LOW = 2; | 62 public static final int REQUEST_PRIORITY_LOW = 2; |
178 /** | 63 /** |
179 * Medium request priority. Passed to {@link #setPriority}. This is the | 64 * Medium request priority. Passed to {@link #setPriority}. This is the |
180 * default priority given to the request. | 65 * default priority given to the request. |
181 */ | 66 */ |
182 public static final int REQUEST_PRIORITY_MEDIUM = 3; | 67 public static final int REQUEST_PRIORITY_MEDIUM = 3; |
183 /** | 68 /** |
184 * Highest request priority. Passed to {@link #setPriority}. | 69 * Highest request priority. Passed to {@link #setPriority}. |
185 */ | 70 */ |
186 public static final int REQUEST_PRIORITY_HIGHEST = 4; | 71 public static final int REQUEST_PRIORITY_HIGHEST = 4; |
187 | 72 |
188 /** | 73 /** |
189 * Sets priority of the request which should be one of the | 74 * Sets priority of the request which should be one of the |
190 * {@link #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values. | 75 * {@link #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values. |
191 * The request is given {@link #REQUEST_PRIORITY_MEDIUM} priority if {@l
ink | 76 * The request is given {@link #REQUEST_PRIORITY_MEDIUM} priority if |
192 * #setPriority} is not called. | 77 * this method is not called. |
193 * | 78 * |
194 * @param priority priority of the request which should be one of the | 79 * @param priority priority of the request which should be one of the |
195 * {@link #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values. | 80 * {@link #REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*} values. |
196 * @return the builder to facilitate chaining. | 81 * @return the builder to facilitate chaining. |
197 */ | 82 */ |
198 public Builder setPriority(@RequestPriority int priority) { | 83 public abstract Builder setPriority(int priority); |
199 mPriority = priority; | |
200 return this; | |
201 } | |
202 | 84 |
203 /** | 85 /** |
204 * Sets upload data provider. Switches method to "POST" if not | 86 * Sets upload data provider. Switches method to "POST" if not |
205 * explicitly set. Starting the request will throw an exception if a | 87 * explicitly set. Starting the request will throw an exception if a |
206 * Content-Type header is not set. | 88 * Content-Type header is not set. |
207 * | 89 * |
208 * @param uploadDataProvider responsible for providing the upload data. | 90 * @param uploadDataProvider responsible for providing the upload data. |
209 * @param executor All {@code uploadDataProvider} methods will be invoke
d | 91 * @param executor All {@code uploadDataProvider} methods will be invoke
d |
210 * using this {@code Executor}. May optionally be the same | 92 * using this {@code Executor}. May optionally be the same |
211 * {@code Executor} the request itself is using. | 93 * {@code Executor} the request itself is using. |
212 * @return the builder to facilitate chaining. | 94 * @return the builder to facilitate chaining. |
213 */ | 95 */ |
214 public Builder setUploadDataProvider( | 96 public abstract Builder setUploadDataProvider( |
215 UploadDataProvider uploadDataProvider, Executor executor) { | 97 UploadDataProvider uploadDataProvider, Executor executor); |
216 if (uploadDataProvider == null) { | |
217 throw new NullPointerException("Invalid UploadDataProvider."); | |
218 } | |
219 if (executor == null) { | |
220 throw new NullPointerException("Invalid UploadDataProvider Execu
tor."); | |
221 } | |
222 if (mMethod == null) { | |
223 mMethod = "POST"; | |
224 } | |
225 mUploadDataProvider = uploadDataProvider; | |
226 mUploadDataProviderExecutor = executor; | |
227 return this; | |
228 } | |
229 | 98 |
230 /** | 99 /** |
231 * Marks that the executors this request will use to notify callbacks (f
or | 100 * Marks that the executors this request will use to notify callbacks (f
or |
232 * {@code UploadDataProvider}s and {@code UrlRequest.Callback}s) is inte
ntionally performing | 101 * {@code UploadDataProvider}s and {@code UrlRequest.Callback}s) is inte
ntionally performing |
233 * inline execution, like Guava's directExecutor or | 102 * inline execution, like Guava's directExecutor or |
234 * {@link java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy}. | 103 * {@link java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy}. |
235 * | 104 * |
236 * <p><b>Warning:</b> This option makes it easy to accidentally block th
e network thread. | 105 * <p><b>Warning:</b> This option makes it easy to accidentally block th
e network thread. |
237 * It should not be used if your callbacks perform disk I/O, acquire loc
ks, or call into | 106 * It should not be used if your callbacks perform disk I/O, acquire loc
ks, or call into |
238 * other code you don't carefully control and audit. | 107 * other code you don't carefully control and audit. |
239 */ | 108 */ |
240 public Builder allowDirectExecutor() { | 109 public abstract Builder allowDirectExecutor(); |
241 mAllowDirectExecutor = true; | |
242 return this; | |
243 } | |
244 | |
245 /** | |
246 * Associates the annotation object with this request. May add more than
one. | |
247 * Passed through to a {@link RequestFinishedInfo.Listener}, | |
248 * see {@link RequestFinishedInfo#getAnnotations}. | |
249 * | |
250 * @param annotation an object to pass on to the {@link RequestFinishedI
nfo.Listener} with a | |
251 * {@link RequestFinishedInfo}. | |
252 * @return the builder to facilitate chaining. | |
253 * | |
254 * @hide as it's a prototype. | |
255 */ | |
256 public Builder addRequestAnnotation(Object annotation) { | |
257 if (annotation == null) { | |
258 throw new NullPointerException("Invalid metrics annotation."); | |
259 } | |
260 if (mRequestAnnotations.isEmpty()) { | |
261 mRequestAnnotations = new ArrayList<Object>(); | |
262 } | |
263 mRequestAnnotations.add(annotation); | |
264 return this; | |
265 } | |
266 | 110 |
267 /** | 111 /** |
268 * Creates a {@link UrlRequest} using configuration within this | 112 * Creates a {@link UrlRequest} using configuration within this |
269 * {@link Builder}. The returned {@code UrlRequest} can then be started | 113 * {@link Builder}. The returned {@code UrlRequest} can then be started |
270 * by calling {@link UrlRequest#start}. | 114 * by calling {@link UrlRequest#start}. |
271 * | 115 * |
272 * @return constructed {@link UrlRequest} using configuration within | 116 * @return constructed {@link UrlRequest} using configuration within |
273 * this {@link Builder}. | 117 * this {@link Builder}. |
274 */ | 118 */ |
275 public UrlRequest build() { | 119 public abstract UrlRequest build(); |
276 final UrlRequest request = mCronetEngine.createRequest(mUrl, mCallba
ck, mExecutor, | |
277 mPriority, mRequestAnnotations, mDisableCache, mDisableConne
ctionMigration, | |
278 mAllowDirectExecutor); | |
279 if (mMethod != null) { | |
280 request.setHttpMethod(mMethod); | |
281 } | |
282 for (Pair<String, String> header : mRequestHeaders) { | |
283 request.addHeader(header.first, header.second); | |
284 } | |
285 if (mUploadDataProvider != null) { | |
286 request.setUploadDataProvider(mUploadDataProvider, mUploadDataPr
oviderExecutor); | |
287 } | |
288 return request; | |
289 } | |
290 } | 120 } |
291 | 121 |
292 /** | 122 /** |
293 * Users of Cronet extend this class to receive callbacks indicating the | 123 * Users of Cronet extend this class to receive callbacks indicating the |
294 * progress of a {@link UrlRequest} being processed. An instance of this cla
ss | 124 * progress of a {@link UrlRequest} being processed. An instance of this cla
ss |
295 * is passed in to {@link UrlRequest.Builder}'s constructor when | 125 * is passed in to {@link UrlRequest.Builder}'s constructor when |
296 * constructing the {@code UrlRequest}. | 126 * constructing the {@code UrlRequest}. |
297 * <p> | 127 * <p> |
298 * Note: All methods will be invoked on the thread of the | 128 * Note: All methods will be invoked on the thread of the |
299 * {@link java.util.concurrent.Executor} used during construction of the | 129 * {@link java.util.concurrent.Executor} used during construction of the |
300 * {@code UrlRequest}. | 130 * {@code UrlRequest}. |
301 */ | 131 */ |
302 public abstract class Callback { | 132 public abstract static class Callback { |
303 /** | 133 /** |
304 * Invoked whenever a redirect is encountered. This will only be invoked | 134 * Invoked whenever a redirect is encountered. This will only be invoked |
305 * between the call to {@link UrlRequest#start} and | 135 * between the call to {@link UrlRequest#start} and |
306 * {@link Callback#onResponseStarted onResponseStarted()}. | 136 * {@link Callback#onResponseStarted onResponseStarted()}. |
307 * The body of the redirect response, if it has one, will be ignored. | 137 * The body of the redirect response, if it has one, will be ignored. |
308 * | 138 * |
309 * The redirect will not be followed until the URLRequest's | 139 * The redirect will not be followed until the URLRequest's |
310 * {@link UrlRequest#followRedirect} method is called, either | 140 * {@link UrlRequest#followRedirect} method is called, either |
311 * synchronously or asynchronously. | 141 * synchronously or asynchronously. |
312 * | 142 * |
(...skipping 83 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
396 * @param info Response information. May be {@code null} if no response
was | 226 * @param info Response information. May be {@code null} if no response
was |
397 * received. | 227 * received. |
398 */ | 228 */ |
399 public void onCanceled(UrlRequest request, UrlResponseInfo info) {} | 229 public void onCanceled(UrlRequest request, UrlResponseInfo info) {} |
400 } | 230 } |
401 | 231 |
402 /** | 232 /** |
403 * Request status values returned by {@link #getStatus}. | 233 * Request status values returned by {@link #getStatus}. |
404 */ | 234 */ |
405 public static class Status { | 235 public static class Status { |
406 /** @hide */ | |
407 @IntDef({ | |
408 INVALID, IDLE, WAITING_FOR_STALLED_SOCKET_POOL, WAITING_FOR_AVAI
LABLE_SOCKET, | |
409 WAITING_FOR_DELEGATE, WAITING_FOR_CACHE, DOWNLOADING_PROXY_SCRIP
T, | |
410 RESOLVING_PROXY_FOR_URL, RESOLVING_HOST_IN_PROXY_SCRIPT, ESTABLI
SHING_PROXY_TUNNEL, | |
411 RESOLVING_HOST, CONNECTING, SSL_HANDSHAKE, SENDING_REQUEST, WAIT
ING_FOR_RESPONSE, | |
412 READING_RESPONSE, | |
413 }) | |
414 @Retention(RetentionPolicy.SOURCE) | |
415 public @interface StatusValues {} | |
416 | 236 |
417 /** | 237 /** |
418 * This state indicates that the request is completed, canceled, or is n
ot | 238 * This state indicates that the request is completed, canceled, or is n
ot |
419 * started. | 239 * started. |
420 */ | 240 */ |
421 public static final int INVALID = -1; | 241 public static final int INVALID = -1; |
422 /** | 242 /** |
423 * This state corresponds to a resource load that has either not yet beg
un | 243 * This state corresponds to a resource load that has either not yet beg
un |
424 * or is idle waiting for the consumer to do something to move things al
ong | 244 * or is idle waiting for the consumer to do something to move things al
ong |
425 * (e.g. when the consumer of a {@link UrlRequest} has not called | 245 * (e.g. when the consumer of a {@link UrlRequest} has not called |
(...skipping 84 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
510 * This state corresponds to a resource load that is blocked waiting for
a | 330 * This state corresponds to a resource load that is blocked waiting for
a |
511 * read to complete. In the case of a HTTP transaction, this corresponds
to | 331 * read to complete. In the case of a HTTP transaction, this corresponds
to |
512 * the period after the response headers have been received and before a
ll | 332 * the period after the response headers have been received and before a
ll |
513 * of the response body has been downloaded. (NOTE: This state only appl
ies | 333 * of the response body has been downloaded. (NOTE: This state only appl
ies |
514 * for an {@link UrlRequest} while there is an outstanding | 334 * for an {@link UrlRequest} while there is an outstanding |
515 * {@link UrlRequest#read read()} operation.) | 335 * {@link UrlRequest#read read()} operation.) |
516 */ | 336 */ |
517 public static final int READING_RESPONSE = 14; | 337 public static final int READING_RESPONSE = 14; |
518 | 338 |
519 private Status() {} | 339 private Status() {} |
520 | |
521 /** | |
522 * Convert a LoadState int to one of values listed above. | |
523 * @param loadState a LoadState to convert. | |
524 * @return static int Status. | |
525 * @hide only used by internal implementation. | |
526 */ | |
527 @StatusValues | |
528 public static int convertLoadState(int loadState) { | |
529 assert loadState >= LoadState.IDLE && loadState <= LoadState.READING
_RESPONSE; | |
530 switch (loadState) { | |
531 case (LoadState.IDLE): | |
532 return IDLE; | |
533 | |
534 case (LoadState.WAITING_FOR_STALLED_SOCKET_POOL): | |
535 return WAITING_FOR_STALLED_SOCKET_POOL; | |
536 | |
537 case (LoadState.WAITING_FOR_AVAILABLE_SOCKET): | |
538 return WAITING_FOR_AVAILABLE_SOCKET; | |
539 | |
540 case (LoadState.WAITING_FOR_DELEGATE): | |
541 return WAITING_FOR_DELEGATE; | |
542 | |
543 case (LoadState.WAITING_FOR_CACHE): | |
544 return WAITING_FOR_CACHE; | |
545 | |
546 case (LoadState.DOWNLOADING_PROXY_SCRIPT): | |
547 return DOWNLOADING_PROXY_SCRIPT; | |
548 | |
549 case (LoadState.RESOLVING_PROXY_FOR_URL): | |
550 return RESOLVING_PROXY_FOR_URL; | |
551 | |
552 case (LoadState.RESOLVING_HOST_IN_PROXY_SCRIPT): | |
553 return RESOLVING_HOST_IN_PROXY_SCRIPT; | |
554 | |
555 case (LoadState.ESTABLISHING_PROXY_TUNNEL): | |
556 return ESTABLISHING_PROXY_TUNNEL; | |
557 | |
558 case (LoadState.RESOLVING_HOST): | |
559 return RESOLVING_HOST; | |
560 | |
561 case (LoadState.CONNECTING): | |
562 return CONNECTING; | |
563 | |
564 case (LoadState.SSL_HANDSHAKE): | |
565 return SSL_HANDSHAKE; | |
566 | |
567 case (LoadState.SENDING_REQUEST): | |
568 return SENDING_REQUEST; | |
569 | |
570 case (LoadState.WAITING_FOR_RESPONSE): | |
571 return WAITING_FOR_RESPONSE; | |
572 | |
573 case (LoadState.READING_RESPONSE): | |
574 return READING_RESPONSE; | |
575 | |
576 default: | |
577 // A load state is retrieved but there is no corresponding | |
578 // request status. This most likely means that the mapping i
s | |
579 // incorrect. | |
580 throw new IllegalArgumentException("No request status found.
"); | |
581 } | |
582 } | |
583 } | 340 } |
584 | 341 |
585 /** | 342 /** |
586 * Listener class used with {@link #getStatus} to receive the status of a | 343 * Listener class used with {@link #getStatus} to receive the status of a |
587 * {@link UrlRequest}. | 344 * {@link UrlRequest}. |
588 */ | 345 */ |
589 public abstract class StatusListener { | 346 public abstract static class StatusListener { |
590 /** | 347 /** |
591 * Invoked on {@link UrlRequest}'s {@link Executor}'s thread when reques
t | 348 * Invoked on {@link UrlRequest}'s {@link Executor}'s thread when reques
t |
592 * status is obtained. | 349 * status is obtained. |
593 * @param status integer representing the status of the request. It is | 350 * @param status integer representing the status of the request. It is |
594 * one of the values defined in {@link Status}. | 351 * one of the values defined in {@link Status}. |
595 */ | 352 */ |
596 public abstract void onStatus(@Status.StatusValues int status); | 353 public abstract void onStatus(int status); |
597 } | 354 } |
598 | 355 |
599 /** | 356 /** |
600 * Sets the HTTP method verb to use for this request. Must be done before | |
601 * request has started. | |
602 * | |
603 * <p>The default when this method is not called is "GET" if the request has | |
604 * no body or "POST" if it does. | |
605 * | |
606 * @param method "GET", "HEAD", "DELETE", "POST" or "PUT". | |
607 * @deprecated Use {@link Builder#setHttpMethod}. | |
608 * @hide | |
609 */ | |
610 @Deprecated public void setHttpMethod(String method); | |
611 | |
612 /** | |
613 * Adds a request header. Must be done before request has started. | |
614 * | |
615 * @param header header name. | |
616 * @param value header value. | |
617 * @deprecated Use {@link Builder#setPriority}. | |
618 * @hide | |
619 */ | |
620 @Deprecated public void addHeader(String header, String value); | |
621 | |
622 /** | |
623 * Sets upload data provider. Must be done before request has started. May o
nly be | |
624 * invoked once per request. Switches method to "POST" if not explicitly | |
625 * set. Starting the request will throw an exception if a Content-Type | |
626 * header is not set. | |
627 * | |
628 * @param uploadDataProvider responsible for providing the upload data. | |
629 * @param executor All {@code uploadDataProvider} methods will be invoked | |
630 * using this {@code Executor}. May optionally be the same | |
631 * {@code Executor} the request itself is using. | |
632 * @deprecated Use {@link Builder#setUploadDataProvider}. | |
633 * @hide | |
634 */ | |
635 @Deprecated | |
636 public void setUploadDataProvider(UploadDataProvider uploadDataProvider, Exe
cutor executor); | |
637 | |
638 /** | |
639 * Starts the request, all callbacks go to {@link Callback}. May only be cal
led | 357 * Starts the request, all callbacks go to {@link Callback}. May only be cal
led |
640 * once. May not be called if {@link #cancel} has been called. | 358 * once. May not be called if {@link #cancel} has been called. |
641 */ | 359 */ |
642 public void start(); | 360 public abstract void start(); |
643 | 361 |
644 /** | 362 /** |
645 * Follows a pending redirect. Must only be called at most once for each | 363 * Follows a pending redirect. Must only be called at most once for each |
646 * invocation of {@link Callback#onRedirectReceived | 364 * invocation of {@link Callback#onRedirectReceived |
647 * onRedirectReceived()}. | 365 * onRedirectReceived()}. |
648 */ | 366 */ |
649 public void followRedirect(); | 367 public abstract void followRedirect(); |
650 | 368 |
651 /** | 369 /** |
652 * Attempts to read part of the response body into the provided buffer. | 370 * Attempts to read part of the response body into the provided buffer. |
653 * Must only be called at most once in response to each invocation of the | 371 * Must only be called at most once in response to each invocation of the |
654 * {@link Callback#onResponseStarted onResponseStarted()} and {@link | 372 * {@link Callback#onResponseStarted onResponseStarted()} and {@link |
655 * Callback#onReadCompleted onReadCompleted()} methods of the {@link | 373 * Callback#onReadCompleted onReadCompleted()} methods of the {@link |
656 * Callback}. Each call will result in an asynchronous call to | 374 * Callback}. Each call will result in an asynchronous call to |
657 * either the {@link Callback Callback's} | 375 * either the {@link Callback Callback's} |
658 * {@link Callback#onReadCompleted onReadCompleted()} method if data | 376 * {@link Callback#onReadCompleted onReadCompleted()} method if data |
659 * is read, its {@link Callback#onSucceeded onSucceeded()} method if | 377 * is read, its {@link Callback#onSucceeded onSucceeded()} method if |
660 * there's no more data to read, or its {@link Callback#onFailed | 378 * there's no more data to read, or its {@link Callback#onFailed |
661 * onFailed()} method if there's an error. | 379 * onFailed()} method if there's an error. |
662 * | 380 * |
663 * @param buffer {@link ByteBuffer} to write response body to. Must be a | 381 * @param buffer {@link ByteBuffer} to write response body to. Must be a |
664 * direct ByteBuffer. The embedder must not read or modify buffer's | 382 * direct ByteBuffer. The embedder must not read or modify buffer's |
665 * position, limit, or data between its position and limit until the | 383 * position, limit, or data between its position and limit until the |
666 * request calls back into the {@link Callback}. | 384 * request calls back into the {@link Callback}. |
667 */ | 385 */ |
668 public void read(ByteBuffer buffer); | 386 public abstract void read(ByteBuffer buffer); |
669 | 387 |
670 /** | 388 /** |
671 * Cancels the request. Can be called at any time. | 389 * Cancels the request. Can be called at any time. |
672 * {@link Callback#onCanceled onCanceled()} will be invoked when cancellatio
n | 390 * {@link Callback#onCanceled onCanceled()} will be invoked when cancellatio
n |
673 * is complete and no further callback methods will be invoked. If the | 391 * is complete and no further callback methods will be invoked. If the |
674 * request has completed or has not started, calling {@code cancel()} has no | 392 * request has completed or has not started, calling {@code cancel()} has no |
675 * effect and {@code onCanceled()} will not be invoked. If the | 393 * effect and {@code onCanceled()} will not be invoked. If the |
676 * {@link Executor} passed in during {@code UrlRequest} construction runs | 394 * {@link Executor} passed in during {@code UrlRequest} construction runs |
677 * tasks on a single thread, and {@code cancel()} is called on that thread, | 395 * tasks on a single thread, and {@code cancel()} is called on that thread, |
678 * no callback methods (besides {@code onCanceled()}) will be invoked after | 396 * no callback methods (besides {@code onCanceled()}) will be invoked after |
679 * {@code cancel()} is called. Otherwise, at most one callback method may be | 397 * {@code cancel()} is called. Otherwise, at most one callback method may be |
680 * invoked after {@code cancel()} has completed. | 398 * invoked after {@code cancel()} has completed. |
681 */ | 399 */ |
682 public void cancel(); | 400 public abstract void cancel(); |
683 | 401 |
684 /** | 402 /** |
685 * Returns {@code true} if the request was successfully started and is now | 403 * Returns {@code true} if the request was successfully started and is now |
686 * finished (completed, canceled, or failed). | 404 * finished (completed, canceled, or failed). |
687 * @return {@code true} if the request was successfully started and is now | 405 * @return {@code true} if the request was successfully started and is now |
688 * finished (completed, canceled, or failed). | 406 * finished (completed, canceled, or failed). |
689 */ | 407 */ |
690 public boolean isDone(); | 408 public abstract boolean isDone(); |
691 | 409 |
692 /** | 410 /** |
693 * Queries the status of the request. | 411 * Queries the status of the request. |
694 * @param listener a {@link StatusListener} that will be invoked with | 412 * @param listener a {@link StatusListener} that will be invoked with |
695 * the request's current status. {@code listener} will be invoked | 413 * the request's current status. {@code listener} will be invoked |
696 * back on the {@link Executor} passed in when the request was | 414 * back on the {@link Executor} passed in when the request was |
697 * created. | 415 * created. |
698 */ | 416 */ |
699 public void getStatus(final StatusListener listener); | 417 public abstract void getStatus(final StatusListener listener); |
700 | 418 |
701 // Note: There are deliberately no accessors for the results of the request | 419 // Note: There are deliberately no accessors for the results of the request |
702 // here. Having none removes any ambiguity over when they are populated, | 420 // here. Having none removes any ambiguity over when they are populated, |
703 // particularly in the redirect case. | 421 // particularly in the redirect case. |
704 } | 422 } |
OLD | NEW |