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.Map; | |
16 import java.util.concurrent.Executor; | 10 import java.util.concurrent.Executor; |
17 | 11 |
18 /** | 12 /** |
19 * 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. |
20 * Created using {@link BidirectionalStream.Builder}. | 14 * Created using {@link BidirectionalStream.Builder}. |
pauljensen
2016/09/20 19:01:37
This needs to be updated.
kapishnikov
2016/09/22 21:32:03
Done. Also added {@hide} since this is an experime
| |
21 * | 15 * |
22 * Note: There are ordering restrictions on methods of {@link BidirectionalStrea m}; | 16 * Note: There are ordering restrictions on methods of {@link BidirectionalStrea m}; |
23 * please see individual methods for description of restrictions. | 17 * please see individual methods for description of restrictions. |
24 */ | 18 */ |
25 public abstract class BidirectionalStream { | 19 public abstract class BidirectionalStream { |
pauljensen
2016/09/20 19:01:37
can this now be an interface?
kapishnikov
2016/09/22 21:32:03
Making it an interface will prohibit us from addin
| |
26 /** | 20 /** |
27 * Builder for {@link BidirectionalStream}s. Allows configuring stream befor e constructing | 21 * Builder for {@link BidirectionalStream}s. Allows configuring stream befor e constructing |
28 * it via {@link Builder#build}. | 22 * it via {@link Builder#build}. |
29 */ | 23 */ |
30 public static class Builder { | 24 public abstract static class Builder { |
pauljensen
2016/09/20 19:01:36
ditto
kapishnikov
2016/09/22 21:32:03
Same reason.
| |
31 // All fields are temporary storage of BidirectionalStream configuration to be | |
32 // copied to BidirectionalStream. | |
33 | |
34 // CronetEngine to create the stream. | |
35 private final CronetEngine mCronetEngine; | |
36 // URL to request. | |
37 private final String mUrl; | |
38 // Callback to receive progress callbacks. | |
39 private final Callback mCallback; | |
40 // Executor on which callbacks will be invoked. | |
41 private final Executor mExecutor; | |
42 // List of request headers, stored as header field name and value pairs. | |
43 private final ArrayList<Map.Entry<String, String>> mRequestHeaders = | |
44 new ArrayList<Map.Entry<String, String>>(); | |
45 | |
46 // HTTP method for the request. Default to POST. | |
47 private String mHttpMethod = "POST"; | |
48 // Priority of the stream. Default is medium. | |
49 @StreamPriority private int mPriority = STREAM_PRIORITY_MEDIUM; | |
50 | |
51 private boolean mDelayRequestHeadersUntilFirstFlush; | |
52 | |
53 /** | |
54 * Creates a builder for {@link BidirectionalStream} objects. All callba cks for | |
55 * generated {@code BidirectionalStream} objects will be invoked on | |
56 * {@code executor}. {@code executor} must not run tasks on the | |
57 * current thread, otherwise the networking operations may block and exc eptions | |
58 * may be thrown at shutdown time. | |
59 * | |
60 * @param url the URL for the generated stream | |
61 * @param callback the {@link Callback} object that gets invoked upon di fferent events | |
62 * occuring | |
63 * @param executor the {@link Executor} on which {@code callback} method s will be invoked | |
64 * @param cronetEngine the {@link CronetEngine} used to create the strea m | |
65 */ | |
66 public Builder( | |
67 String url, Callback callback, Executor executor, CronetEngine c ronetEngine) { | |
68 if (url == null) { | |
69 throw new NullPointerException("URL is required."); | |
70 } | |
71 if (callback == null) { | |
72 throw new NullPointerException("Callback is required."); | |
73 } | |
74 if (executor == null) { | |
75 throw new NullPointerException("Executor is required."); | |
76 } | |
77 if (cronetEngine == null) { | |
78 throw new NullPointerException("CronetEngine is required."); | |
79 } | |
80 mUrl = url; | |
81 mCallback = callback; | |
82 mExecutor = executor; | |
83 mCronetEngine = cronetEngine; | |
84 } | |
85 | |
86 /** | 25 /** |
87 * Sets the HTTP method for the request. Returns builder to facilitate c haining. | 26 * Sets the HTTP method for the request. Returns builder to facilitate c haining. |
88 * | 27 * |
89 * @param method the method to use for request. Default is 'POST' | 28 * @param method the method to use for request. Default is 'POST' |
90 * @return the builder to facilitate chaining | 29 * @return the builder to facilitate chaining |
91 */ | 30 */ |
92 public Builder setHttpMethod(String method) { | 31 public abstract Builder setHttpMethod(String method); |
93 if (method == null) { | |
94 throw new NullPointerException("Method is required."); | |
95 } | |
96 mHttpMethod = method; | |
97 return this; | |
98 } | |
99 | 32 |
100 /** | 33 /** |
101 * Adds a request header. Returns builder to facilitate chaining. | 34 * Adds a request header. Returns builder to facilitate chaining. |
102 * | 35 * |
103 * @param header the header name | 36 * @param header the header name |
104 * @param value the header value | 37 * @param value the header value |
105 * @return the builder to facilitate chaining | 38 * @return the builder to facilitate chaining |
106 */ | 39 */ |
107 public Builder addHeader(String header, String value) { | 40 public abstract Builder addHeader(String header, String value); |
108 if (header == null) { | |
109 throw new NullPointerException("Invalid header name."); | |
110 } | |
111 if (value == null) { | |
112 throw new NullPointerException("Invalid header value."); | |
113 } | |
114 mRequestHeaders.add( | |
115 new AbstractMap.SimpleImmutableEntry<String, String>(header, value)); | |
116 return this; | |
117 } | |
118 | |
119 /** @hide */ | |
120 @IntDef({ | |
121 STREAM_PRIORITY_IDLE, STREAM_PRIORITY_LOWEST, STREAM_PRIORITY_LO W, | |
122 STREAM_PRIORITY_MEDIUM, STREAM_PRIORITY_HIGHEST, | |
123 }) | |
124 @Retention(RetentionPolicy.SOURCE) | |
125 public @interface StreamPriority {} | |
126 | 41 |
127 /** | 42 /** |
128 * Lowest stream priority. Passed to {@link #setPriority}. | 43 * Lowest stream priority. Passed to {@link #setPriority}. |
129 */ | 44 */ |
130 public static final int STREAM_PRIORITY_IDLE = 0; | 45 public static final int STREAM_PRIORITY_IDLE = 0; |
131 /** | 46 /** |
132 * Very low stream priority. Passed to {@link #setPriority}. | 47 * Very low stream priority. Passed to {@link #setPriority}. |
133 */ | 48 */ |
134 public static final int STREAM_PRIORITY_LOWEST = 1; | 49 public static final int STREAM_PRIORITY_LOWEST = 1; |
135 /** | 50 /** |
(...skipping 13 matching lines...) Expand all Loading... | |
149 /** | 64 /** |
150 * Sets priority of the stream which should be one of the | 65 * Sets priority of the stream which should be one of the |
151 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. | 66 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. |
152 * The stream is given {@link #STREAM_PRIORITY_MEDIUM} priority if {@lin k | 67 * The stream is given {@link #STREAM_PRIORITY_MEDIUM} priority if {@lin k |
153 * #setPriority} is not called. | 68 * #setPriority} is not called. |
154 * | 69 * |
155 * @param priority priority of the stream which should be one of the | 70 * @param priority priority of the stream which should be one of the |
156 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. | 71 * {@link #STREAM_PRIORITY_IDLE STREAM_PRIORITY_*} values. |
157 * @return the builder to facilitate chaining. | 72 * @return the builder to facilitate chaining. |
158 */ | 73 */ |
159 public Builder setPriority(@StreamPriority int priority) { | 74 public abstract Builder setPriority(int priority); |
160 mPriority = priority; | |
161 return this; | |
162 } | |
163 | 75 |
164 /** | 76 /** |
165 * Delays sending request headers until {@link BidirectionalStream#flush ()} | 77 * Delays sending request headers until {@link BidirectionalStream#flush ()} |
166 * is called. This flag is currently only respected when QUIC is negotia ted. | 78 * is called. This flag is currently only respected when QUIC is negotia ted. |
167 * When true, QUIC will send request header frame along with data frame( s) | 79 * When true, QUIC will send request header frame along with data frame( s) |
168 * as a single packet when possible. | 80 * as a single packet when possible. |
169 * | 81 * |
170 * @param delayRequestHeadersUntilFirstFlush if true, sending request he aders will | 82 * @param delayRequestHeadersUntilFirstFlush if true, sending request he aders will |
171 * be delayed until flush() is called. | 83 * be delayed until flush() is called. |
172 * @return the builder to facilitate chaining. | 84 * @return the builder to facilitate chaining. |
173 */ | 85 */ |
174 public Builder delayRequestHeadersUntilFirstFlush( | 86 public abstract Builder delayRequestHeadersUntilFirstFlush( |
175 boolean delayRequestHeadersUntilFirstFlush) { | 87 boolean delayRequestHeadersUntilFirstFlush); |
176 mDelayRequestHeadersUntilFirstFlush = delayRequestHeadersUntilFirstF lush; | |
177 return this; | |
178 } | |
179 | 88 |
180 /** | 89 /** |
181 * Creates a {@link BidirectionalStream} using configuration from this | 90 * Creates a {@link BidirectionalStream} using configuration from this |
182 * {@link Builder}. The returned {@code BidirectionalStream} can then be started | 91 * {@link Builder}. The returned {@code BidirectionalStream} can then be started |
183 * by calling {@link BidirectionalStream#start}. | 92 * by calling {@link BidirectionalStream#start}. |
184 * | 93 * |
185 * @return constructed {@link BidirectionalStream} using configuration f rom | 94 * @return constructed {@link BidirectionalStream} using configuration f rom |
186 * this {@link Builder} | 95 * this {@link Builder} |
187 */ | 96 */ |
188 @SuppressLint("WrongConstant") // TODO(jbudorick): Remove this after rol ling to the N SDK. | 97 @SuppressLint("WrongConstant") // TODO(jbudorick): Remove this after rol ling to the N SDK. |
189 public BidirectionalStream build() { | 98 public abstract BidirectionalStream build(); |
190 return mCronetEngine.createBidirectionalStream(mUrl, mCallback, mExe cutor, mHttpMethod, | |
191 mRequestHeaders, mPriority, mDelayRequestHeadersUntilFirstFl ush); | |
192 } | |
193 } | 99 } |
194 | 100 |
195 /** | 101 /** |
196 * Callback class used to receive callbacks from a {@link BidirectionalStrea m}. | 102 * Callback class used to receive callbacks from a {@link BidirectionalStrea m}. |
197 */ | 103 */ |
198 public abstract static class Callback { | 104 public abstract static class Callback { |
199 /** | 105 /** |
200 * Invoked when the stream is ready for reading and writing. | 106 * Invoked when the stream is ready for reading and writing. |
201 * Consumer may call {@link BidirectionalStream#read read()} to start re ading data. | 107 * Consumer may call {@link BidirectionalStream#read read()} to start re ading data. |
202 * Consumer may call {@link BidirectionalStream#write write()} to start writing data. | 108 * Consumer may call {@link BidirectionalStream#write write()} to start writing data. |
(...skipping 182 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
385 /** | 291 /** |
386 * Returns {@code true} if the stream was successfully started and is now | 292 * Returns {@code true} if the stream was successfully started and is now |
387 * done (succeeded, canceled, or failed). | 293 * done (succeeded, canceled, or failed). |
388 * | 294 * |
389 * @return {@code true} if the stream was successfully started and is now | 295 * @return {@code true} if the stream was successfully started and is now |
390 * done (completed, canceled, or failed), otherwise returns {@code f alse} | 296 * done (completed, canceled, or failed), otherwise returns {@code f alse} |
391 * to indicate stream is not yet started or is in progress. | 297 * to indicate stream is not yet started or is in progress. |
392 */ | 298 */ |
393 public abstract boolean isDone(); | 299 public abstract boolean isDone(); |
394 } | 300 } |
OLD | NEW |