Added Network Quality Estimator Real-time interface to Cronet

components/cronet/android/java/src/org/chromium/net/UrlRequestContext.java

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package org.chromium.net;
 
 import android.content.Context;
 import android.util.Log;
 
 import java.lang.reflect.Constructor;
@@ skipping 76 matching lines @@
      */
     public abstract void startNetLogToFile(String fileName, boolean logAll);
 
     /**
      * Stops NetLog logging and flushes file to disk. If a logging session is
      * not in progress, this call is ignored.
      */
     public abstract void stopNetLog();
 
     /**
+     * Enables the network quality estimator, which collects and reports
+     * measurements of round trip time (RTT) and downstream throughput at
+     * various layers of the network stack. After enabling the estimator,
+     * observers of RTT and throughput can be added with
+     * {@link #addRttObserver} and {@link #addThroughputObserver} and
+     * removed with {@link #removeRttObserver} and
+     * {@link #removeThroughputObserver}. The estimator uses memory and CPU
+     * only when enabled.
+     * @param executor an executor that will be used to notified all
+     *            added RTT and throughput observers.
+     */
+    public abstract void enableNetworkQualityEstimator(Executor executor);

[mef, 2015/09/25 19:06:42]

I wonder whether this must be a runtime method, or should it be a parameter on
UrlRequestContextConfig?

[bengr, 2015/09/29 23:22:50]

Since this is experimental, let's leave it as a separate runtime method.

+
+    /**
+     * Enables the network quality estimator for testing. This must be called
+     * before round trip time and throughput observers are added. Set both
+     * boolean parameters to false for default behavior.
+     * @param useLocalHostRequests include requests to localhost in estimates.
+     * @param useSmallerResponses include small responses in throughput estimates.
+     * @param executor an {@link java.util.concurrent.Executor} on which all
+     *            observers will be called.
+     */
+    abstract void enableNetworkQualityEstimator(
+            boolean useLocalHostRequests, boolean useSmallerResponses, Executor executor);
+
+    /**
+     * Registers an observer that gets called whenever the network quality
+     * estimator witnesses a sample round trip time. This must be called
+     * after {@link #enableNetworkQualityEstimator}. Round trip times may be
+     * recorded at various layers of the network stack, including TCP, QUIC,
+     * and at the URL request layer. The observer is called on the
+     * {@link java.util.concurrent.Executor} that is passed to
+     * {@link #enableNetworkQualityEstimator}.
+     * @param observer the observer of round trip times.
+     */
+    public abstract void addRttObserver(NetworkQualityRttObserver observer);
+
+    /**
+     * Removes an observer of round trip times if on the observer list. This
+     * should be called after an RttObserver is added in order to stop
+     * receiving observations.
+     * @param observer the observer of round trip times.
+     */
+    public abstract void removeRttObserver(NetworkQualityRttObserver observer);
+
+    /**
+     * Registers an observer that gets called whenever the network quality
+     * estimator witnesses a sample throughput measurement. This must be called
+     * after {@link #enableNetworkQualityEstimator}. Throughput observations
+     * are computed by measuring bytes read over the active network interface
+     * at times when at least one URL response is being received. The observer
+     * is called on the {@link java.util.concurrent.Executor} that is passed to
+     * {@link #enableNetworkQualityEstimator}.
+     * @param observer the observer of throughput.
+     */
+    public abstract void addThroughputObserver(NetworkQualityThroughputObserver observer);
+
+    /**
+     * Removes an observer of throughput. This should be called after a
+     * ThroughputObserver is added in order to stop receiving observations.
+     * @param observer the observer of throughput.
+     */
+    public abstract void removeThroughputObserver(NetworkQualityThroughputObserver observer);
+
+    /**
      * Creates a {@link UrlRequestContext} with the given
      * {@link UrlRequestContextConfig}.
      * @param context Android {@link Context}.
      * @param config context configuration.
      */
     public static UrlRequestContext createContext(Context context,
             UrlRequestContextConfig config) {
         UrlRequestContext urlRequestContext = null;
         if (config.userAgent().isEmpty()) {
             config.setUserAgent(UserAgent.from(context));
@@ skipping 30 matching lines @@
         } catch (ClassNotFoundException e) {
             // Leave as null.
         } catch (Exception e) {
             throw new IllegalStateException(
                     "Cannot instantiate: " + CRONET_URL_REQUEST_CONTEXT,
                     e);
         }
         return urlRequestContext;
     }
 }