OLD | NEW |
---|---|
(Empty) | |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 package org.chromium.net; | |
5 | |
6 import android.content.Context; | |
7 | |
8 import java.io.IOException; | |
9 import java.net.Proxy; | |
10 import java.net.URL; | |
11 import java.net.URLConnection; | |
12 import java.util.Date; | |
13 import java.util.Set; | |
14 import java.util.concurrent.Executor; | |
15 | |
16 /** | |
17 * {@link CronetEngine} that exposes experimental features. Use {@link Builder} to build an | |
18 * instance of this class. Every instance of {@link CronetEngine} can be casted to an instance | |
19 * of this class. | |
20 * | |
21 * {@hide since this class exposes experimental features that should be hidden.} | |
22 */ | |
23 public abstract class ExperimentalCronetEngine extends CronetEngine { | |
24 /** | |
25 * Builder for building {@link ExperimentalCronetEngine}. | |
26 * {@hide since this class exposes experimental features that should be hidd en.} | |
pauljensen
2016/10/03 15:22:36
is this @hide necessary considering the parent cla
kapishnikov
2016/10/03 23:49:27
Removed.
| |
27 */ | |
28 public static class Builder extends CronetEngine.Builder { | |
29 /** | |
30 * Default config enables SPDY, disables QUIC, SDCH and HTTP cache. | |
31 * | |
32 * @param context Android {@link Context} for engine to use. | |
33 */ | |
34 public Builder(Context context) { | |
35 super(context); | |
36 } | |
37 | |
38 /** | |
39 * Enables the network quality estimator, which collects and reports | |
40 * measurements of round trip time (RTT) and downstream throughput at | |
41 * various layers of the network stack. After enabling the estimator, | |
42 * listeners of RTT and throughput can be added with | |
43 * {@link #addRttListener} and {@link #addThroughputListener} and | |
44 * removed with {@link #removeRttListener} and | |
45 * {@link #removeThroughputListener}. The estimator uses memory and CPU | |
46 * only when enabled. | |
47 * @param value {@code true} to enable network quality estimator, | |
48 * {@code false} to disable. | |
49 * @return the builder to facilitate chaining. | |
50 */ | |
51 public Builder enableNetworkQualityEstimator(boolean value) { | |
52 mBuilderDelegate.enableNetworkQualityEstimator(value); | |
53 return this; | |
54 } | |
55 | |
56 /** | |
57 * Initializes CachingCertVerifier's cache with certVerifierData which h as | |
58 * the results of certificate verification. | |
59 * @param certVerifierData a serialized representation of certificate | |
60 * verification results. | |
61 * @return the builder to facilitate chaining. | |
62 */ | |
63 public Builder setCertVerifierData(String certVerifierData) { | |
64 mBuilderDelegate.setCertVerifierData(certVerifierData); | |
65 return this; | |
66 } | |
67 | |
68 public Builder setDataReductionProxyOptions( | |
pauljensen
2016/10/03 15:22:36
eh where did the comment for this method go?
kapishnikov
2016/10/03 23:49:27
Restored the comment back.
| |
69 String primaryProxy, String fallbackProxy, String secureProxyChe ckUrl) { | |
70 mBuilderDelegate.setDataReductionProxyOptions( | |
71 primaryProxy, fallbackProxy, secureProxyCheckUrl); | |
72 return this; | |
73 } | |
74 | |
75 /** | |
76 * Build an instance of {@link ExperimentalCronetEngine} | |
77 * | |
78 * @return the constructed experimental engine. | |
79 */ | |
80 public ExperimentalCronetEngine build() { | |
pauljensen
2016/10/03 15:22:37
remove comment, add @Override, move to the end of
kapishnikov
2016/10/03 23:49:27
Done.
| |
81 return (ExperimentalCronetEngine) super.build(); | |
82 } | |
83 | |
84 /** | |
85 * Sets whether the resulting {@link CronetEngine} uses an | |
86 * implementation based on the system's | |
87 * {@link java.net.HttpURLConnection} implementation, or if this is | |
88 * only done as a backup if the native implementation fails to load. | |
89 * Defaults to disabled. | |
90 * @param value {@code true} makes the resulting {@link CronetEngine} | |
91 * use an implementation based on the system's | |
92 * {@link java.net.HttpURLConnection} implementation | |
93 * without trying to load the native implementation. | |
94 * {@code false} makes the resulting {@code CronetEngine} | |
95 * use the native implementation, or if that fails to load, | |
96 * falls back to an implementation based on the system's | |
97 * {@link java.net.HttpURLConnection} implementation. | |
98 * @return the builder to facilitate chaining. | |
99 */ | |
100 public Builder enableLegacyMode(boolean value) { | |
101 mBuilderDelegate.enableLegacyMode(value); | |
102 return this; | |
103 } | |
104 | |
105 /** | |
106 * Enables | |
107 * <a href="https://developer.chrome.com/multidevice/data-compression">D ata | |
108 * Reduction Proxy</a>. Defaults to disabled. | |
109 * @param key key to use when authenticating with the proxy. | |
110 * @return the builder to facilitate chaining. | |
111 */ | |
112 public Builder enableDataReductionProxy(String key) { | |
113 mBuilderDelegate.enableDataReductionProxy(key); | |
114 return this; | |
115 } | |
116 | |
117 ICronetEngineBuilder getBuilderDelegate() { | |
pauljensen
2016/10/03 15:22:37
@VisibleForTesting
kapishnikov
2016/10/03 23:49:27
Added. I used @android.support.annotation.VisibleF
| |
118 return mBuilderDelegate; | |
119 } | |
120 | |
121 // To support method chaining, override superclass methods to return an | |
122 // instance of this class instead of the parent. | |
123 | |
124 @Override | |
125 public Builder setUserAgent(String userAgent) { | |
126 super.setUserAgent(userAgent); | |
127 return this; | |
128 } | |
129 | |
130 @Override | |
131 public Builder setStoragePath(String value) { | |
132 super.setStoragePath(value); | |
133 return this; | |
134 } | |
135 | |
136 @Override | |
137 public Builder setLibraryLoader(LibraryLoader loader) { | |
138 super.setLibraryLoader(loader); | |
139 return this; | |
140 } | |
141 | |
142 @Override | |
143 public Builder enableQuic(boolean value) { | |
144 super.enableQuic(value); | |
145 return this; | |
146 } | |
147 | |
148 @Override | |
149 public Builder enableHttp2(boolean value) { | |
150 super.enableHttp2(value); | |
151 return this; | |
152 } | |
153 | |
154 @Override | |
155 public Builder enableSdch(boolean value) { | |
156 super.enableSdch(value); | |
157 return this; | |
158 } | |
159 | |
160 @Override | |
161 public Builder enableHttpCache(int cacheMode, long maxSize) { | |
162 super.enableHttpCache(cacheMode, maxSize); | |
163 return this; | |
164 } | |
165 | |
166 @Override | |
167 public Builder addQuicHint(String host, int port, int alternatePort) { | |
168 super.addQuicHint(host, port, alternatePort); | |
169 return this; | |
170 } | |
171 | |
172 @Override | |
173 public Builder addPublicKeyPins(String hostName, Set<byte[]> pinsSha256, | |
174 boolean includeSubdomains, Date expirationDate) { | |
175 super.addPublicKeyPins(hostName, pinsSha256, includeSubdomains, expi rationDate); | |
176 return this; | |
177 } | |
178 | |
179 @Override | |
180 public Builder enablePublicKeyPinningBypassForLocalTrustAnchors(boolean value) { | |
181 super.enablePublicKeyPinningBypassForLocalTrustAnchors(value); | |
182 return this; | |
183 } | |
184 | |
185 @Override | |
186 public Builder setExperimentalOptions(String options) { | |
187 super.setExperimentalOptions(options); | |
188 return this; | |
189 } | |
190 } | |
191 | |
192 /** | |
193 * Creates a builder for {@link BidirectionalStream} objects. All callbacks for | |
194 * generated {@code BidirectionalStream} objects will be invoked on | |
195 * {@code executor}. {@code executor} must not run tasks on the | |
196 * current thread, otherwise the networking operations may block and excepti ons | |
197 * may be thrown at shutdown time. | |
198 * | |
199 * @param url the URL for the generated stream. | |
pauljensen
2016/10/03 15:22:37
this description differs in "the" and plurality of
kapishnikov
2016/10/03 23:49:27
Done.
| |
200 * @param callback the {@link BidirectionalStream.Callback} object that gets invoked upon | |
201 * different events occurring. | |
202 * @param executor the {@link Executor} on which {@code callback} methods wi ll be invoked. | |
203 * | |
204 * @return the created builder. | |
205 */ | |
206 public abstract ExperimentalBidirectionalStream.Builder newBidirectionalStre amBuilder( | |
207 String url, BidirectionalStream.Callback callback, Executor executor ); | |
208 | |
209 @Override | |
210 public abstract ExperimentalUrlRequest.Builder newUrlRequestBuilder( | |
211 String url, UrlRequest.Callback callback, Executor executor); | |
212 | |
213 /** | |
214 * Starts NetLog logging to a specified directory with a bounded size. The N etLog will contain | |
215 * events emitted by all live CronetEngines. The NetLog is useful for debugg ing. | |
216 * The log can be viewed by stitching the files using net/log/stitch_net_log _files.py and | |
217 * using a Chrome browser navigated to chrome://net-internals/#import | |
218 * @param dirPath the directory where the log files will be created. It must already exist. | |
219 * NetLog files must not already exist in the directory. If activ ely logging, | |
220 * this method is ignored. | |
221 * @param logAll {@code true} to include basic events, user cookies, | |
222 * credentials and all transferred bytes in the log. This option presents a | |
223 * privacy risk, since it exposes the user's credentials, and sho uld only be | |
224 * used with the user's consent and in situations where the log w on't be public. | |
225 * {@code false} to just include basic events. | |
226 * @param maxSize the maximum total disk space in bytes that should be used by NetLog. Actual | |
227 * disk space usage may exceed this limit slightly. | |
228 */ | |
229 public abstract void startNetLogToDisk(String dirPath, boolean logAll, int m axSize); | |
230 | |
231 /** | |
232 * Returns the effective connection type computed by the network quality | |
233 * estimator. | |
234 */ | |
235 public abstract int getEffectiveConnectionType(); | |
236 | |
237 /** | |
238 * Configures the network quality estimator for testing. This must be called | |
239 * before round trip time and throughput listeners are added, and after the | |
240 * network quality estimator has been enabled. | |
241 * @param useLocalHostRequests include requests to localhost in estimates. | |
242 * @param useSmallerResponses include small responses in throughput | |
243 * estimates. | |
244 */ | |
245 public abstract void configureNetworkQualityEstimatorForTesting( | |
246 boolean useLocalHostRequests, boolean useSmallerResponses); | |
247 | |
248 /** | |
249 * Registers a listener that gets called whenever the network quality | |
250 * estimator witnesses a sample round trip time. This must be called | |
251 * after {@link Builder#enableNetworkQualityEstimator}, and with throw an | |
252 * exception otherwise. Round trip times may be recorded at various layers | |
253 * of the network stack, including TCP, QUIC, and at the URL request layer. | |
254 * The listener is called on the {@link java.util.concurrent.Executor} that | |
255 * is passed to {@link Builder#enableNetworkQualityEstimator}. | |
256 * @param listener the listener of round trip times. | |
257 */ | |
258 public abstract void addRttListener(NetworkQualityRttListener listener); | |
259 | |
260 /** | |
261 * Removes a listener of round trip times if previously registered with | |
262 * {@link #addRttListener}. This should be called after a | |
263 * {@link NetworkQualityRttListener} is added in order to stop receiving | |
264 * observations. | |
265 * @param listener the listener of round trip times. | |
266 */ | |
267 public abstract void removeRttListener(NetworkQualityRttListener listener); | |
268 | |
269 /** | |
270 * Registers a listener that gets called whenever the network quality | |
271 * estimator witnesses a sample throughput measurement. This must be called | |
272 * after {@link Builder#enableNetworkQualityEstimator}. Throughput observati ons | |
273 * are computed by measuring bytes read over the active network interface | |
274 * at times when at least one URL response is being received. The listener | |
275 * is called on the {@link java.util.concurrent.Executor} that is passed to | |
276 * {@link Builder#enableNetworkQualityEstimator}. | |
277 * @param listener the listener of throughput. | |
278 */ | |
279 public abstract void addThroughputListener(NetworkQualityThroughputListener listener); | |
280 | |
281 /** | |
282 * Removes a listener of throughput. This should be called after a | |
283 * {@link NetworkQualityThroughputListener} is added with | |
284 * {@link #addThroughputListener} in order to stop receiving observations. | |
285 * @param listener the listener of throughput. | |
286 */ | |
287 public abstract void removeThroughputListener(NetworkQualityThroughputListen er listener); | |
288 | |
289 /** | |
290 * Establishes a new connection to the resource specified by the {@link URL} {@code url} | |
291 * using the given proxy. | |
292 * <p> | |
293 * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation i s subject to certain | |
294 * limitations, see {@link #createURLStreamHandlerFactory} for details. | |
295 * | |
296 * @param url URL of resource to connect to. | |
297 * @param proxy proxy to use when establishing connection. | |
298 * @return an {@link java.net.HttpURLConnection} instance implemented by thi s CronetEngine. | |
299 * @throws IOException if an error occurs while opening the connection. | |
300 */ | |
301 // TODO(pauljensen): Expose once implemented, http://crbug.com/418111 | |
302 public abstract URLConnection openConnection(URL url, Proxy proxy) throws IO Exception; | |
303 | |
304 /** | |
305 * Registers a listener that gets called after the end of each request with the request info. | |
306 * | |
307 * <p>This must be called after {@link Builder#enableNetworkQualityEstimator } and will throw an | |
308 * exception otherwise. | |
309 * | |
310 * <p>The listener is called on the {@link java.util.concurrent.Executor} th at | |
311 * is passed to {@link Builder#enableNetworkQualityEstimator}. | |
312 * | |
313 * @param listener the listener for finished requests. | |
314 */ | |
315 | |
pauljensen
2016/10/03 15:22:37
extra newline
kapishnikov
2016/10/03 23:49:27
Removed.
| |
316 public abstract void addRequestFinishedListener(RequestFinishedInfo.Listener listener); | |
317 | |
318 /** | |
319 * Removes a finished request listener. | |
320 * | |
321 * @param listener the listener to remove. | |
322 */ | |
323 public abstract void removeRequestFinishedListener(RequestFinishedInfo.Liste ner listener); | |
324 | |
325 /** | |
326 * Returns serialized representation of certificate verifier's cache | |
327 * which contains the list of hosts/certificates and the certificate | |
328 * verification results. May block until data is received from the network | |
329 * thread (will timeout after the specified timeout). In case of timeout, it | |
330 * returns the previous saved value. | |
331 * | |
332 * @param timeout in milliseconds. If timeout is 0, it will use default valu e. | |
333 * @return serialized representation of certificate verification results | |
334 * data. | |
335 */ | |
336 public abstract String getCertVerifierData(long timeout); | |
337 } | |
OLD | NEW |