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.concurrent.Executor; | |
13 | |
14 /** | |
15 * {@link CronetEngine} that exposes experimental features. Use {@link Builder} to build an | |
16 * instance of this class. | |
17 * {@hide} since this class exposes experimental features that should be hidden. | |
18 */ | |
19 public abstract class ExperimentalCronetEngine extends CronetEngine { | |
pauljensen
2016/09/20 19:01:37
can this be an interface?
kapishnikov
2016/09/22 21:32:03
See the previous comment.
| |
20 /** | |
21 * Builder for building {@link ExperimentalCronetEngine}. | |
22 * {@hide} since this class exposes experimental features that should be hid den. | |
pauljensen
2016/09/20 19:01:37
Is the inner @hide necessary? I wouldn't have tho
kapishnikov
2016/09/22 21:32:03
Removed.
| |
23 */ | |
24 public static class Builder extends CronetEngine.Builder { | |
25 /** | |
26 * Default config enables SPDY, disables QUIC, SDCH and HTTP cache. | |
27 * | |
28 * @param context Android {@link Context} for engine to use. | |
29 */ | |
30 public Builder(Context context) { | |
31 super(context); | |
32 } | |
33 | |
34 /** | |
35 * Enables the network quality estimator, which collects and reports | |
36 * measurements of round trip time (RTT) and downstream throughput at | |
37 * various layers of the network stack. After enabling the estimator, | |
38 * listeners of RTT and throughput can be added with | |
39 * {@link #addRttListener} and {@link #addThroughputListener} and | |
40 * removed with {@link #removeRttListener} and | |
41 * {@link #removeThroughputListener}. The estimator uses memory and CPU | |
42 * only when enabled. | |
43 * @param value {@code true} to enable network quality estimator, | |
44 * {@code false} to disable. | |
45 * @return the builder to facilitate chaining. | |
46 */ | |
47 public Builder enableNetworkQualityEstimator(boolean value) { | |
48 mBuilderDelegate.enableNetworkQualityEstimator(value); | |
49 return this; | |
50 } | |
51 | |
52 /** | |
53 * Initializes CachingCertVerifier's cache with certVerifierData which h as | |
54 * the results of certificate verification. | |
55 * @param certVerifierData a serialized representation of certificate | |
56 * verification results. | |
57 * @return the builder to facilitate chaining. | |
58 */ | |
59 public Builder setCertVerifierData(String certVerifierData) { | |
60 mBuilderDelegate.setCertVerifierData(certVerifierData); | |
61 return this; | |
62 } | |
63 | |
64 public Builder setDataReductionProxyOptions( | |
65 String primaryProxy, String fallbackProxy, String secureProxyChe ckUrl) { | |
66 mBuilderDelegate.setDataReductionProxyOptions( | |
67 primaryProxy, fallbackProxy, secureProxyCheckUrl); | |
68 return this; | |
69 } | |
70 | |
71 /** | |
72 * Build an instance of {@link ExperimentalCronetEngine} | |
73 * | |
74 * @return the constructed experimental engine. | |
75 */ | |
76 public ExperimentalCronetEngine build() { | |
77 return (ExperimentalCronetEngine) mBuilderDelegate.build(); | |
78 } | |
79 } | |
80 | |
81 public abstract BidirectionalStream.Builder newBidirectionalStreamBuilder( | |
pauljensen
2016/09/20 19:01:37
this should either:
1. be moved to CronetEngine, o
pauljensen
2016/09/20 19:01:37
this needs a comment
kapishnikov
2016/09/22 21:32:03
Made BidirectionalStream hidden since it is consid
kapishnikov
2016/09/22 21:32:03
Done.
| |
82 String url, BidirectionalStream.Callback callback, Executor executor ); | |
83 | |
84 /** | |
85 * Starts NetLog logging to a specified directory with a bounded size. The N etLog will contain | |
86 * events emitted by all live CronetEngines. The NetLog is useful for debugg ing. | |
87 * The log can be viewed by stitching the files using net/log/stitch_net_log _files.py and | |
88 * using a Chrome browser navigated to chrome://net-internals/#import | |
89 * @param dirPath the directory where the log files will be created. It must already exist. | |
90 * NetLog files must not already exist in the directory. If activ ely logging, | |
91 * this method is ignored. | |
92 * @param logAll {@code true} to include basic events, user cookies, | |
93 * credentials and all transferred bytes in the log. This option presents a | |
94 * privacy risk, since it exposes the user's credentials, and sho uld only be | |
95 * used with the user's consent and in situations where the log w on't be public. | |
96 * {@code false} to just include basic events. | |
97 * @param maxSize the maximum total disk space in bytes that should be used by NetLog. Actual | |
98 * disk space usage may exceed this limit slightly. | |
99 */ | |
100 public abstract void startNetLogToDisk(String dirPath, boolean logAll, int m axSize); | |
101 | |
102 /** | |
103 * Returns the effective connection type computed by the network quality | |
104 * estimator. | |
105 */ | |
106 public abstract int getEffectiveConnectionType(); | |
107 | |
108 /** | |
109 * Configures the network quality estimator for testing. This must be called | |
110 * before round trip time and throughput listeners are added, and after the | |
111 * network quality estimator has been enabled. | |
112 * @param useLocalHostRequests include requests to localhost in estimates. | |
113 * @param useSmallerResponses include small responses in throughput | |
114 * estimates. | |
115 */ | |
116 public abstract void configureNetworkQualityEstimatorForTesting( | |
117 boolean useLocalHostRequests, boolean useSmallerResponses); | |
118 | |
119 /** | |
120 * Registers a listener that gets called whenever the network quality | |
121 * estimator witnesses a sample round trip time. This must be called | |
122 * after {@link Builder#enableNetworkQualityEstimator}, and with throw an | |
123 * exception otherwise. Round trip times may be recorded at various layers | |
124 * of the network stack, including TCP, QUIC, and at the URL request layer. | |
125 * The listener is called on the {@link java.util.concurrent.Executor} that | |
126 * is passed to {@link Builder#enableNetworkQualityEstimator}. | |
127 * @param listener the listener of round trip times. | |
128 */ | |
129 public abstract void addRttListener(NetworkQualityRttListener listener); | |
130 | |
131 /** | |
132 * Removes a listener of round trip times if previously registered with | |
133 * {@link #addRttListener}. This should be called after a | |
134 * {@link NetworkQualityRttListener} is added in order to stop receiving | |
135 * observations. | |
136 * @param listener the listener of round trip times. | |
137 */ | |
138 public abstract void removeRttListener(NetworkQualityRttListener listener); | |
139 | |
140 /** | |
141 * Registers a listener that gets called whenever the network quality | |
142 * estimator witnesses a sample throughput measurement. This must be called | |
143 * after {@link Builder#enableNetworkQualityEstimator}. Throughput observati ons | |
144 * are computed by measuring bytes read over the active network interface | |
145 * at times when at least one URL response is being received. The listener | |
146 * is called on the {@link java.util.concurrent.Executor} that is passed to | |
147 * {@link Builder#enableNetworkQualityEstimator}. | |
148 * @param listener the listener of throughput. | |
149 */ | |
150 public abstract void addThroughputListener(NetworkQualityThroughputListener listener); | |
151 | |
152 /** | |
153 * Removes a listener of throughput. This should be called after a | |
154 * {@link NetworkQualityThroughputListener} is added with | |
155 * {@link #addThroughputListener} in order to stop receiving observations. | |
156 * @param listener the listener of throughput. | |
157 */ | |
158 public abstract void removeThroughputListener(NetworkQualityThroughputListen er listener); | |
159 | |
160 /** | |
161 * Establishes a new connection to the resource specified by the {@link URL} {@code url} | |
162 * using the given proxy. | |
163 * <p> | |
164 * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation i s subject to certain | |
165 * limitations, see {@link #createURLStreamHandlerFactory} for details. | |
166 * | |
167 * @param url URL of resource to connect to. | |
168 * @param proxy proxy to use when establishing connection. | |
169 * @return an {@link java.net.HttpURLConnection} instance implemented by thi s CronetEngine. | |
170 * @throws IOException if an error occurs while opening the connection. | |
171 * TODO(pauljensen): Expose once implemented, http://crbug.com/418111 | |
pauljensen
2016/09/20 19:01:37
Move this comment to just below the "*/" and use a
kapishnikov
2016/09/22 21:32:03
Good point. Done.
| |
172 */ | |
173 public abstract URLConnection openConnection(URL url, Proxy proxy) throws IO Exception; | |
174 | |
175 /** | |
176 * Registers a listener that gets called after the end of each request with the request info. | |
177 * | |
178 * <p>This must be called after {@link Builder#enableNetworkQualityEstimator } and will throw an | |
179 * exception otherwise. | |
180 * | |
181 * <p>The listener is called on the {@link java.util.concurrent.Executor} th at | |
182 * is passed to {@link Builder#enableNetworkQualityEstimator}. | |
183 * | |
184 * @param listener the listener for finished requests. | |
185 */ | |
186 | |
187 public abstract void addRequestFinishedListener(RequestFinishedInfo.Listener listener); | |
188 | |
189 /** | |
190 * Removes a finished request listener. | |
191 * | |
192 * @param listener the listener to remove. | |
193 */ | |
194 public abstract void removeRequestFinishedListener(RequestFinishedInfo.Liste ner listener); | |
195 | |
196 /** | |
197 * Creates a builder for {@link ExperimentalUrlRequest} objects. All callbac ks for | |
198 * generated {@code ExperimentalUrlRequest} objects will be invoked on | |
199 * {@code executor}'s thread. {@code executor} must not run tasks on the | |
200 * current thread to prevent blocking networking operations and causing | |
201 * exceptions during shutdown. | |
202 * | |
203 * @param url {@link java.net.URL} for the generated requests. | |
204 * @param callback callback object that gets invoked on different events. | |
205 * @param executor {@link Executor} on which all callbacks will be invoked. | |
206 */ | |
207 public abstract UrlRequest.Builder newUrlRequestBuilder( | |
pauljensen
2016/09/20 19:01:37
I think this should be removed, it's redundant wit
kapishnikov
2016/09/22 21:32:03
Done.
| |
208 String url, UrlRequest.Callback callback, Executor executor); | |
209 } | |
OLD | NEW |