1 // Copyright 2016 The Chromium Authors 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 androidx.annotation.VisibleForTesting; 9 10 import java.io.IOException; 11 import java.net.Proxy; 12 import java.net.URL; 13 import java.net.URLConnection; 14 import java.util.Date; 15 import java.util.Set; 16 import java.util.concurrent.Executor; 17 18 /** 19 * {@link CronetEngine} that exposes experimental features. To obtain an instance of this class, 20 * cast a {@code CronetEngine} to this type. Every instance of {@code CronetEngine} can be cast to 21 * an instance of this class, as they are backed by the same implementation and hence perform 22 * identically. Instances of this class are not meant for general use, but instead only to access 23 * experimental features. Experimental features may be deprecated in the future. Use at your own 24 * risk. 25 * 26 * <p>{@hide since this class exposes experimental features that should be hidden.} 27 * 28 * @deprecated scheduled for deletion, don't use in new code. 29 */ 30 @Deprecated 31 public abstract class ExperimentalCronetEngine extends CronetEngine { 32 /** The value of a connection metric is unknown. */ 33 public static final int CONNECTION_METRIC_UNKNOWN = CronetEngine.CONNECTION_METRIC_UNKNOWN; 34 35 /** 36 * The estimate of the effective connection type is unknown. 37 * 38 * @see #getEffectiveConnectionType 39 */ 40 public static final int EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 41 CronetEngine.EFFECTIVE_CONNECTION_TYPE_UNKNOWN; 42 43 /** 44 * The device is offline. 45 * 46 * @see #getEffectiveConnectionType 47 */ 48 public static final int EFFECTIVE_CONNECTION_TYPE_OFFLINE = 49 CronetEngine.EFFECTIVE_CONNECTION_TYPE_OFFLINE; 50 51 /** 52 * The estimate of the effective connection type is slow 2G. 53 * 54 * @see #getEffectiveConnectionType 55 */ 56 public static final int EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 57 CronetEngine.EFFECTIVE_CONNECTION_TYPE_SLOW_2G; 58 59 /** 60 * The estimate of the effective connection type is 2G. 61 * 62 * @see #getEffectiveConnectionType 63 */ 64 public static final int EFFECTIVE_CONNECTION_TYPE_2G = 65 CronetEngine.EFFECTIVE_CONNECTION_TYPE_2G; 66 67 /** 68 * The estimate of the effective connection type is 3G. 69 * 70 * @see #getEffectiveConnectionType 71 */ 72 public static final int EFFECTIVE_CONNECTION_TYPE_3G = 73 CronetEngine.EFFECTIVE_CONNECTION_TYPE_3G; 74 75 /** 76 * The estimate of the effective connection type is 4G. 77 * 78 * @see #getEffectiveConnectionType 79 */ 80 public static final int EFFECTIVE_CONNECTION_TYPE_4G = 81 CronetEngine.EFFECTIVE_CONNECTION_TYPE_4G; 82 83 /** The value to be used to undo any previous network binding. */ 84 public static final long UNBIND_NETWORK_HANDLE = CronetEngine.UNBIND_NETWORK_HANDLE; 85 86 /** 87 * A version of {@link CronetEngine.Builder} that exposes experimental features. Instances of 88 * this class are not meant for general use, but instead only to access experimental features. 89 * Experimental features may be deprecated in the future. Use at your own risk. 90 */ 91 public static class Builder extends CronetEngine.Builder { 92 /** 93 * Constructs a {@link Builder} object that facilitates creating a {@link CronetEngine}. The 94 * default configuration enables HTTP/2 and disables QUIC, SDCH and the HTTP cache. 95 * 96 * @param context Android {@link Context}, which is used by the Builder to retrieve the 97 * application context. A reference to only the application context will be kept, so as 98 * to avoid extending the lifetime of {@code context} unnecessarily. 99 */ Builder(Context context)100 public Builder(Context context) { 101 super(context); 102 } 103 104 /** 105 * Constructs {@link Builder} with a given delegate that provides the actual implementation 106 * of the {@code Builder} methods. This constructor is used only by the internal 107 * implementation. 108 * 109 * @param builderDelegate delegate that provides the actual implementation. 110 * <p>{@hide} 111 */ Builder(ICronetEngineBuilder builderDelegate)112 public Builder(ICronetEngineBuilder builderDelegate) { 113 super(builderDelegate); 114 } 115 116 /** 117 * Sets experimental options to be used in Cronet. 118 * 119 * @param options JSON formatted experimental options. 120 * @return the builder to facilitate chaining. 121 */ setExperimentalOptions(String options)122 public Builder setExperimentalOptions(String options) { 123 mBuilderDelegate.setExperimentalOptions(options); 124 return this; 125 } 126 127 /** 128 * Returns delegate, only for testing. 129 * 130 * @hide 131 */ 132 @VisibleForTesting getBuilderDelegate()133 public ICronetEngineBuilder getBuilderDelegate() { 134 return mBuilderDelegate; 135 } 136 137 // To support method chaining, override superclass methods to return an 138 // instance of this class instead of the parent. 139 140 @Override setUserAgent(String userAgent)141 public Builder setUserAgent(String userAgent) { 142 super.setUserAgent(userAgent); 143 return this; 144 } 145 146 @Override setStoragePath(String value)147 public Builder setStoragePath(String value) { 148 super.setStoragePath(value); 149 return this; 150 } 151 152 @Override setLibraryLoader(LibraryLoader loader)153 public Builder setLibraryLoader(LibraryLoader loader) { 154 super.setLibraryLoader(loader); 155 return this; 156 } 157 158 @Override enableQuic(boolean value)159 public Builder enableQuic(boolean value) { 160 super.enableQuic(value); 161 return this; 162 } 163 164 @Override enableHttp2(boolean value)165 public Builder enableHttp2(boolean value) { 166 super.enableHttp2(value); 167 return this; 168 } 169 170 @Override 171 @QuicOptions.Experimental setQuicOptions(QuicOptions options)172 public Builder setQuicOptions(QuicOptions options) { 173 super.setQuicOptions(options); 174 return this; 175 } 176 177 @Override 178 @DnsOptions.Experimental setDnsOptions(DnsOptions options)179 public Builder setDnsOptions(DnsOptions options) { 180 super.setDnsOptions(options); 181 return this; 182 } 183 184 @Override 185 @ConnectionMigrationOptions.Experimental setConnectionMigrationOptions(ConnectionMigrationOptions options)186 public Builder setConnectionMigrationOptions(ConnectionMigrationOptions options) { 187 super.setConnectionMigrationOptions(options); 188 return this; 189 } 190 191 @Override enableSdch(boolean value)192 public Builder enableSdch(boolean value) { 193 return this; 194 } 195 196 @Override enableHttpCache(int cacheMode, long maxSize)197 public Builder enableHttpCache(int cacheMode, long maxSize) { 198 super.enableHttpCache(cacheMode, maxSize); 199 return this; 200 } 201 202 @Override addQuicHint(String host, int port, int alternatePort)203 public Builder addQuicHint(String host, int port, int alternatePort) { 204 super.addQuicHint(host, port, alternatePort); 205 return this; 206 } 207 208 @Override addPublicKeyPins( String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Date expirationDate)209 public Builder addPublicKeyPins( 210 String hostName, 211 Set<byte[]> pinsSha256, 212 boolean includeSubdomains, 213 Date expirationDate) { 214 super.addPublicKeyPins(hostName, pinsSha256, includeSubdomains, expirationDate); 215 return this; 216 } 217 218 @Override enablePublicKeyPinningBypassForLocalTrustAnchors(boolean value)219 public Builder enablePublicKeyPinningBypassForLocalTrustAnchors(boolean value) { 220 super.enablePublicKeyPinningBypassForLocalTrustAnchors(value); 221 return this; 222 } 223 224 @Override enableNetworkQualityEstimator(boolean value)225 public Builder enableNetworkQualityEstimator(boolean value) { 226 super.enableNetworkQualityEstimator(value); 227 return this; 228 } 229 230 @Override setThreadPriority(int priority)231 public Builder setThreadPriority(int priority) { 232 super.setThreadPriority(priority); 233 return this; 234 } 235 236 @Override build()237 public ExperimentalCronetEngine build() { 238 return mBuilderDelegate.build(); 239 } 240 } 241 242 @Override newBidirectionalStreamBuilder( String url, BidirectionalStream.Callback callback, Executor executor)243 public abstract ExperimentalBidirectionalStream.Builder newBidirectionalStreamBuilder( 244 String url, BidirectionalStream.Callback callback, Executor executor); 245 246 @Override newUrlRequestBuilder( String url, UrlRequest.Callback callback, Executor executor)247 public abstract ExperimentalUrlRequest.Builder newUrlRequestBuilder( 248 String url, UrlRequest.Callback callback, Executor executor); 249 250 /** 251 * Establishes a new connection to the resource specified by the {@link URL} {@code url} using 252 * the given proxy. <p> <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation 253 * is subject to certain limitations, see {@link #createURLStreamHandlerFactory} for details. 254 * 255 * @param url URL of resource to connect to. 256 * @param proxy proxy to use when establishing connection. 257 * @return an {@link java.net.HttpURLConnection} instance implemented by this CronetEngine. 258 * @throws IOException if an error occurs while opening the connection. 259 */ 260 // TODO(pauljensen): Expose once implemented, http://crbug.com/418111 openConnection(URL url, Proxy proxy)261 public URLConnection openConnection(URL url, Proxy proxy) throws IOException { 262 return url.openConnection(proxy); 263 } 264 } 265