OLD | NEW |
---|---|
1 // Copyright 2015 The Chromium Authors. All rights reserved. | 1 // Copyright 2015 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.annotation.SuppressLint; | 7 import android.annotation.SuppressLint; |
8 import android.support.annotation.IntDef; | |
9 | 8 |
10 import java.lang.annotation.Retention; | |
11 import java.lang.annotation.RetentionPolicy; | |
12 import java.nio.ByteBuffer; | 9 import java.nio.ByteBuffer; |
13 import java.util.AbstractMap; | |
14 import java.util.ArrayList; | |
15 import java.util.Collection; | |
16 import java.util.Map; | |
17 import java.util.concurrent.Executor; | 10 import java.util.concurrent.Executor; |
18 | 11 |
19 /** | 12 /** |
20 * Class for bidirectional sending and receiving of data over HTTP/2 or QUIC con nections. | 13 * Class for bidirectional sending and receiving of data over HTTP/2 or QUIC con nections. |
21 * Created using {@link BidirectionalStream.Builder}. | 14 * Created using {@link ExperimentalCronetEngine#newBidirectionalStreamBuilder}. |
pauljensen
2016/10/03 15:22:36
you replaced a type with a method that returns tha
kapishnikov
2016/10/03 23:49:27
Done.
| |
22 * | 15 * |
23 * Note: There are ordering restrictions on methods of {@link BidirectionalStrea m}; | 16 * Note: There are ordering restrictions on methods of {@link BidirectionalStrea m}; |
24 * please see individual methods for description of restrictions. | 17 * please see individual methods for description of restrictions. |
18 * | |
19 * {@hide} experimental. | |
25 */ | 20 */ |
26 public abstract class BidirectionalStream { | 21 public abstract class BidirectionalStream { |
27 /** | 22 /** |
28 * Builder for {@link BidirectionalStream}s. Allows configuring stream befor e constructing | 23 * Builder for {@link BidirectionalStream}s. Allows configuring stream befor e constructing |
29 * it via {@link Builder#build}. | 24 * it via {@link Builder#build}. |
pauljensen
2016/10/03 15:22:36
We need a sentence explaining how to create a Bidi
kapishnikov
2016/10/03 23:49:27
Done.
| |
30 */ | 25 */ |
31 public static class Builder { | 26 public abstract static class Builder { |
32 // All fields are temporary storage of BidirectionalStream configuration to be | |
33 // copied to BidirectionalStream. | |
34 | |
35 // CronetEngine to create the stream. | |
36 private final CronetEngine mCronetEngine; | |
37 // URL to request. | |
38 private final String mUrl; | |
39 // Callback to receive progress callbacks. | |
40 private final Callback mCallback; | |
41 // Executor on which callbacks will be invoked. | |
42 private final Executor mExecutor; | |
43 // List of request headers, stored as header field name and value pairs. | |
44 private final ArrayList<Map.Entry<String, String>> mRequestHeaders = | |
45 new ArrayList<Map.Entry<String, String>>(); | |
46 | |
47 // HTTP method for the request. Default to POST. | |
48 private String mHttpMethod = "POST"; | |
49 // Priority of the stream. Default is medium. | |
50 @StreamPriority private int mPriority = STREAM_PRIORITY_MEDIUM; | |
51 | |
52 private boolean mDelayRequestHeadersUntilFirstFlush; | |
53 | |
54 // Request reporting annotations. | |
55 private Collection<Object> mRequestAnnotations; | |
56 | |
57 /** | |
58 * Creates a builder for {@link BidirectionalStream} objects. All callba cks for | |
59 * generated {@code BidirectionalStream} objects will be invoked on | |
60 * {@code executor}. {@code executor} must not run tasks on the | |
61 * current thread, otherwise the networking operations may block and exc eptions | |
62 * may be thrown at shutdown time. | |
63 * | |
64 * @param url the URL for the generated stream | |
65 * @param callback the {@link Callback} object that gets invoked upon di fferent events | |
66 * occuring | |
67 * @param executor the {@link Executor} on which {@code callback} method s will be invoked | |
68 * @param cronetEngine the {@link CronetEngine} used to create the strea m | |
69 */ | |
70 public Builder( | |
71 String url, Callback callback, Executor executor, CronetEngine c ronetEngine) { | |
72 if (url == null) { | |
73 throw new NullPointerException("URL is required."); | |
74 } | |
75 if (callback == null) { | |
76 throw new NullPointerException("Callback is required."); | |
77 } | |
78 if (executor == null) { | |
79 throw new NullPointerException("Executor is required."); | |
80 } | |
81 if (cronetEngine == null) { | |
82 throw new NullPointerException("CronetEngine is required."); | |
83 } | |
84 mUrl = url; | |
85 mCallback = callback; | |
86 mExecutor = executor; | |
87 mCronetEngine = cronetEngine; | |
88 } | |
89 | |
90 /** | 27 /** |
91 * Sets the HTTP method for the request. Returns builder to facilitate c haining. | 28 * Sets the HTTP method for the request. Returns builder to facilitate c haining. |
92 * | 29 * |
93 * @param method the method to use for request. Default is 'POST' | 30 * @param method the method to use for request. Default is 'POST' |
94 * @return the builder to facilitate chaining | 31 * @return the builder to facilitate chaining |
95 */ | 32 */ |
96 public Builder setHttpMethod(String method) { | 33 public abstract Builder setHttpMethod(String method); |
97 if (method == null) { | |
98 throw new NullPointerException("Method is required."); | |
99 } | |
100 mHttpMethod = method; | |
101 return this; | |
102 } | |
103 | 34 |
104 /** | 35 /** |
105 * Adds a request header. Returns builder to facilitate chaining. | 36 * Adds a request header. Returns builder to facilitate chaining. |
106 * | 37 * |
107 * @param header the header name | 38 * @param header the header name |
108 * @param value the header value | 39 * @param value the header value |
109 * @return the builder to facilitate chaining | 40 * @return the builder to facilitate chaining |
110 */ | 41 */ |
111 public Builder addHeader(String header, String value) { | 42 public abstract Builder addHeader(String header, String value); |
112 if (header == null) { | |
113 throw new NullPointerException("Invalid header name."); | |
114 } | |
115 if (value == null) { | |
116 throw new NullPointerException("Invalid header value."); | |
117 } | |
118 mRequestHeaders.add( | |
119 new AbstractMap.SimpleImmutableEntry<String, String>(header, value)); | |
120 return this; | |
121 } | |
122 | |
123 /** @hide */ | |
124 @IntDef({ | |
125 STREAM_PRIORITY_IDLE, STREAM_PRIORITY_LOWEST, STREAM_PRIORITY_LO W, | |
126 STREAM_PRIORITY_MEDIUM, STREAM_PRIORITY_HIGHEST, | |
127 }) | |
128 @Retention(RetentionPolicy.SOURCE) | |
129 public @interface StreamPriority {} | |
130 | 43 |
131 /** | 44 /** |
132 * Lowest stream priority. Passed to {@link #setPriority}. | 45 * Lowest stream priority. Passed to {@link #setPriority}. |
133 */ | 46 */ |
134 public static final int STREAM_PRIORITY_IDLE = 0; | 47 public static final int STREAM_PRIORITY_IDLE = 0; |
135 /** | 48 /** |
136 * Very low stream priority. Passed to {@link #setPriority}. | 49 * Very low stream priority. Passed to {@link #setPriority}. |
137 */ | 50 */ |
138 public static final int STREAM_PRIORITY_LOWEST = 1; | 51 public static final int STREAM_PRIORITY_LOWEST = 1; |
139 /** | 52 /** |
(...skipping 13 matching lines...) Expand all Loading... | |
153 /** | 66 /** |
154 * Sets priority of the stream which should be one of the | 67 * Sets priority of the stream which should be one of the |
155 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. | 68 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. |
156 * The stream is given {@link #STREAM_PRIORITY_MEDIUM} priority if {@lin k | 69 * The stream is given {@link #STREAM_PRIORITY_MEDIUM} priority if {@lin k |
157 * #setPriority} is not called. | 70 * #setPriority} is not called. |
158 * | 71 * |
159 * @param priority priority of the stream which should be one of the | 72 * @param priority priority of the stream which should be one of the |
160 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. | 73 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. |
161 * @return the builder to facilitate chaining. | 74 * @return the builder to facilitate chaining. |
162 */ | 75 */ |
163 public Builder setPriority(@StreamPriority int priority) { | 76 public abstract Builder setPriority(int priority); |
164 mPriority = priority; | |
165 return this; | |
166 } | |
167 | 77 |
168 /** | 78 /** |
169 * Delays sending request headers until {@link BidirectionalStream#flush ()} | 79 * Delays sending request headers until {@link BidirectionalStream#flush ()} |
170 * is called. This flag is currently only respected when QUIC is negotia ted. | 80 * is called. This flag is currently only respected when QUIC is negotia ted. |
171 * When true, QUIC will send request header frame along with data frame( s) | 81 * When true, QUIC will send request header frame along with data frame( s) |
172 * as a single packet when possible. | 82 * as a single packet when possible. |
173 * | 83 * |
174 * @param delayRequestHeadersUntilFirstFlush if true, sending request he aders will | 84 * @param delayRequestHeadersUntilFirstFlush if true, sending request he aders will |
175 * be delayed until flush() is called. | 85 * be delayed until flush() is called. |
176 * @return the builder to facilitate chaining. | 86 * @return the builder to facilitate chaining. |
177 */ | 87 */ |
178 public Builder delayRequestHeadersUntilFirstFlush( | 88 public abstract Builder delayRequestHeadersUntilFirstFlush( |
179 boolean delayRequestHeadersUntilFirstFlush) { | 89 boolean delayRequestHeadersUntilFirstFlush); |
180 mDelayRequestHeadersUntilFirstFlush = delayRequestHeadersUntilFirstF lush; | |
181 return this; | |
182 } | |
183 | |
184 /** | |
185 * Associates the annotation object with this request. May add more than one. | |
186 * Passed through to a {@link RequestFinishedInfo.Listener}, | |
187 * see {@link RequestFinishedInfo#getAnnotations}. | |
188 * | |
189 * @param annotation an object to pass on to the {@link RequestFinishedI nfo.Listener} with a | |
190 * {@link RequestFinishedInfo}. | |
191 * @return the builder to facilitate chaining. | |
192 * | |
193 * @hide as it's a prototype. | |
194 */ | |
195 public Builder addRequestAnnotation(Object annotation) { | |
196 if (annotation == null) { | |
197 throw new NullPointerException("Invalid metrics annotation."); | |
198 } | |
199 if (mRequestAnnotations == null) { | |
200 mRequestAnnotations = new ArrayList<Object>(); | |
201 } | |
202 mRequestAnnotations.add(annotation); | |
203 return this; | |
204 } | |
205 | 90 |
206 /** | 91 /** |
207 * Creates a {@link BidirectionalStream} using configuration from this | 92 * Creates a {@link BidirectionalStream} using configuration from this |
208 * {@link Builder}. The returned {@code BidirectionalStream} can then be started | 93 * {@link Builder}. The returned {@code BidirectionalStream} can then be started |
209 * by calling {@link BidirectionalStream#start}. | 94 * by calling {@link BidirectionalStream#start}. |
210 * | 95 * |
211 * @return constructed {@link BidirectionalStream} using configuration f rom | 96 * @return constructed {@link BidirectionalStream} using configuration f rom |
212 * this {@link Builder} | 97 * this {@link Builder} |
213 */ | 98 */ |
214 @SuppressLint("WrongConstant") // TODO(jbudorick): Remove this after rol ling to the N SDK. | 99 @SuppressLint("WrongConstant") // TODO(jbudorick): Remove this after rol ling to the N SDK. |
215 public BidirectionalStream build() { | 100 public abstract BidirectionalStream build(); |
216 return mCronetEngine.createBidirectionalStream(mUrl, mCallback, mExe cutor, mHttpMethod, | |
217 mRequestHeaders, mPriority, mDelayRequestHeadersUntilFirstFl ush, | |
218 mRequestAnnotations); | |
219 } | |
220 } | 101 } |
221 | 102 |
222 /** | 103 /** |
223 * Callback class used to receive callbacks from a {@link BidirectionalStrea m}. | 104 * Callback class used to receive callbacks from a {@link BidirectionalStrea m}. |
224 */ | 105 */ |
225 public abstract static class Callback { | 106 public abstract static class Callback { |
226 /** | 107 /** |
227 * Invoked when the stream is ready for reading and writing. | 108 * Invoked when the stream is ready for reading and writing. |
228 * Consumer may call {@link BidirectionalStream#read read()} to start re ading data. | 109 * Consumer may call {@link BidirectionalStream#read read()} to start re ading data. |
229 * Consumer may call {@link BidirectionalStream#write write()} to start writing data. | 110 * Consumer may call {@link BidirectionalStream#write write()} to start writing data. |
(...skipping 182 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
412 /** | 293 /** |
413 * Returns {@code true} if the stream was successfully started and is now | 294 * Returns {@code true} if the stream was successfully started and is now |
414 * done (succeeded, canceled, or failed). | 295 * done (succeeded, canceled, or failed). |
415 * | 296 * |
416 * @return {@code true} if the stream was successfully started and is now | 297 * @return {@code true} if the stream was successfully started and is now |
417 * done (completed, canceled, or failed), otherwise returns {@code f alse} | 298 * done (completed, canceled, or failed), otherwise returns {@code f alse} |
418 * to indicate stream is not yet started or is in progress. | 299 * to indicate stream is not yet started or is in progress. |
419 */ | 300 */ |
420 public abstract boolean isDone(); | 301 public abstract boolean isDone(); |
421 } | 302 } |
OLD | NEW |