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.} |
| 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( |
| 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() { |
| 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 ICronetEngineBuilder getBuilderDelegate() { |
| 106 return mBuilderDelegate; |
| 107 } |
| 108 |
| 109 // To support method chaining, override superclass methods to return an |
| 110 // instance of this class instead of the parent. |
| 111 |
| 112 @Override |
| 113 public Builder setUserAgent(String userAgent) { |
| 114 super.setUserAgent(userAgent); |
| 115 return this; |
| 116 } |
| 117 |
| 118 @Override |
| 119 public Builder setStoragePath(String value) { |
| 120 super.setStoragePath(value); |
| 121 return this; |
| 122 } |
| 123 |
| 124 @Override |
| 125 public Builder setLibraryLoader(LibraryLoader loader) { |
| 126 super.setLibraryLoader(loader); |
| 127 return this; |
| 128 } |
| 129 |
| 130 @Override |
| 131 public Builder enableQuic(boolean value) { |
| 132 super.enableQuic(value); |
| 133 return this; |
| 134 } |
| 135 |
| 136 @Override |
| 137 public Builder enableHttp2(boolean value) { |
| 138 super.enableHttp2(value); |
| 139 return this; |
| 140 } |
| 141 |
| 142 @Override |
| 143 public Builder enableSdch(boolean value) { |
| 144 super.enableSdch(value); |
| 145 return this; |
| 146 } |
| 147 |
| 148 @Override |
| 149 public Builder enableDataReductionProxy(String key) { |
| 150 super.enableDataReductionProxy(key); |
| 151 return this; |
| 152 } |
| 153 |
| 154 @Override |
| 155 public Builder enableHttpCache(int cacheMode, long maxSize) { |
| 156 super.enableHttpCache(cacheMode, maxSize); |
| 157 return this; |
| 158 } |
| 159 |
| 160 @Override |
| 161 public Builder addQuicHint(String host, int port, int alternatePort) { |
| 162 super.addQuicHint(host, port, alternatePort); |
| 163 return this; |
| 164 } |
| 165 |
| 166 @Override |
| 167 public Builder addPublicKeyPins(String hostName, Set<byte[]> pinsSha256, |
| 168 boolean includeSubdomains, Date expirationDate) { |
| 169 super.addPublicKeyPins(hostName, pinsSha256, includeSubdomains, expi
rationDate); |
| 170 return this; |
| 171 } |
| 172 |
| 173 @Override |
| 174 public Builder enablePublicKeyPinningBypassForLocalTrustAnchors(boolean
value) { |
| 175 super.enablePublicKeyPinningBypassForLocalTrustAnchors(value); |
| 176 return this; |
| 177 } |
| 178 |
| 179 @Override |
| 180 public Builder setExperimentalOptions(String options) { |
| 181 super.setExperimentalOptions(options); |
| 182 return this; |
| 183 } |
| 184 } |
| 185 |
| 186 /** |
| 187 * Creates a builder for {@link BidirectionalStream} objects. All callbacks
for |
| 188 * generated {@code BidirectionalStream} objects will be invoked on |
| 189 * {@code executor}. {@code executor} must not run tasks on the |
| 190 * current thread, otherwise the networking operations may block and excepti
ons |
| 191 * may be thrown at shutdown time. |
| 192 * |
| 193 * @param url the URL for the generated stream. |
| 194 * @param callback the {@link BidirectionalStream.Callback} object that gets
invoked upon |
| 195 * different events occurring. |
| 196 * @param executor the {@link Executor} on which {@code callback} methods wi
ll be invoked. |
| 197 * |
| 198 * @return the created builder. |
| 199 */ |
| 200 public abstract ExperimentalBidirectionalStream.Builder newBidirectionalStre
amBuilder( |
| 201 String url, BidirectionalStream.Callback callback, Executor executor
); |
| 202 |
| 203 /** |
| 204 * Starts NetLog logging to a specified directory with a bounded size. The N
etLog will contain |
| 205 * events emitted by all live CronetEngines. The NetLog is useful for debugg
ing. |
| 206 * The log can be viewed by stitching the files using net/log/stitch_net_log
_files.py and |
| 207 * using a Chrome browser navigated to chrome://net-internals/#import |
| 208 * @param dirPath the directory where the log files will be created. It must
already exist. |
| 209 * NetLog files must not already exist in the directory. If activ
ely logging, |
| 210 * this method is ignored. |
| 211 * @param logAll {@code true} to include basic events, user cookies, |
| 212 * credentials and all transferred bytes in the log. This option
presents a |
| 213 * privacy risk, since it exposes the user's credentials, and sho
uld only be |
| 214 * used with the user's consent and in situations where the log w
on't be public. |
| 215 * {@code false} to just include basic events. |
| 216 * @param maxSize the maximum total disk space in bytes that should be used
by NetLog. Actual |
| 217 * disk space usage may exceed this limit slightly. |
| 218 */ |
| 219 public abstract void startNetLogToDisk(String dirPath, boolean logAll, int m
axSize); |
| 220 |
| 221 /** |
| 222 * Returns the effective connection type computed by the network quality |
| 223 * estimator. |
| 224 */ |
| 225 public abstract int getEffectiveConnectionType(); |
| 226 |
| 227 /** |
| 228 * Configures the network quality estimator for testing. This must be called |
| 229 * before round trip time and throughput listeners are added, and after the |
| 230 * network quality estimator has been enabled. |
| 231 * @param useLocalHostRequests include requests to localhost in estimates. |
| 232 * @param useSmallerResponses include small responses in throughput |
| 233 * estimates. |
| 234 */ |
| 235 public abstract void configureNetworkQualityEstimatorForTesting( |
| 236 boolean useLocalHostRequests, boolean useSmallerResponses); |
| 237 |
| 238 /** |
| 239 * Registers a listener that gets called whenever the network quality |
| 240 * estimator witnesses a sample round trip time. This must be called |
| 241 * after {@link Builder#enableNetworkQualityEstimator}, and with throw an |
| 242 * exception otherwise. Round trip times may be recorded at various layers |
| 243 * of the network stack, including TCP, QUIC, and at the URL request layer. |
| 244 * The listener is called on the {@link java.util.concurrent.Executor} that |
| 245 * is passed to {@link Builder#enableNetworkQualityEstimator}. |
| 246 * @param listener the listener of round trip times. |
| 247 */ |
| 248 public abstract void addRttListener(NetworkQualityRttListener listener); |
| 249 |
| 250 /** |
| 251 * Removes a listener of round trip times if previously registered with |
| 252 * {@link #addRttListener}. This should be called after a |
| 253 * {@link NetworkQualityRttListener} is added in order to stop receiving |
| 254 * observations. |
| 255 * @param listener the listener of round trip times. |
| 256 */ |
| 257 public abstract void removeRttListener(NetworkQualityRttListener listener); |
| 258 |
| 259 /** |
| 260 * Registers a listener that gets called whenever the network quality |
| 261 * estimator witnesses a sample throughput measurement. This must be called |
| 262 * after {@link Builder#enableNetworkQualityEstimator}. Throughput observati
ons |
| 263 * are computed by measuring bytes read over the active network interface |
| 264 * at times when at least one URL response is being received. The listener |
| 265 * is called on the {@link java.util.concurrent.Executor} that is passed to |
| 266 * {@link Builder#enableNetworkQualityEstimator}. |
| 267 * @param listener the listener of throughput. |
| 268 */ |
| 269 public abstract void addThroughputListener(NetworkQualityThroughputListener
listener); |
| 270 |
| 271 /** |
| 272 * Removes a listener of throughput. This should be called after a |
| 273 * {@link NetworkQualityThroughputListener} is added with |
| 274 * {@link #addThroughputListener} in order to stop receiving observations. |
| 275 * @param listener the listener of throughput. |
| 276 */ |
| 277 public abstract void removeThroughputListener(NetworkQualityThroughputListen
er listener); |
| 278 |
| 279 /** |
| 280 * Establishes a new connection to the resource specified by the {@link URL}
{@code url} |
| 281 * using the given proxy. |
| 282 * <p> |
| 283 * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation i
s subject to certain |
| 284 * limitations, see {@link #createURLStreamHandlerFactory} for details. |
| 285 * |
| 286 * @param url URL of resource to connect to. |
| 287 * @param proxy proxy to use when establishing connection. |
| 288 * @return an {@link java.net.HttpURLConnection} instance implemented by thi
s CronetEngine. |
| 289 * @throws IOException if an error occurs while opening the connection. |
| 290 */ |
| 291 // TODO(pauljensen): Expose once implemented, http://crbug.com/418111 |
| 292 public abstract URLConnection openConnection(URL url, Proxy proxy) throws IO
Exception; |
| 293 |
| 294 /** |
| 295 * Registers a listener that gets called after the end of each request with
the request info. |
| 296 * |
| 297 * <p>This must be called after {@link Builder#enableNetworkQualityEstimator
} and will throw an |
| 298 * exception otherwise. |
| 299 * |
| 300 * <p>The listener is called on the {@link java.util.concurrent.Executor} th
at |
| 301 * is passed to {@link Builder#enableNetworkQualityEstimator}. |
| 302 * |
| 303 * @param listener the listener for finished requests. |
| 304 */ |
| 305 |
| 306 public abstract void addRequestFinishedListener(RequestFinishedInfo.Listener
listener); |
| 307 |
| 308 /** |
| 309 * Removes a finished request listener. |
| 310 * |
| 311 * @param listener the listener to remove. |
| 312 */ |
| 313 public abstract void removeRequestFinishedListener(RequestFinishedInfo.Liste
ner listener); |
| 314 } |
OLD | NEW |