Download doclava when building for Android and use to build cronet Javadocs

components/cronet/android/api/src/org/chromium/net/CronetEngine.java

 // Copyright 2015 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.net.http.HttpResponseCache;
 import android.support.annotation.IntDef;
 import android.support.annotation.Nullable;
 import android.util.Log;
 
 import java.io.File;
 import java.io.IOException;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.reflect.Constructor;
 import java.net.IDN;
 import java.net.Proxy;
 import java.net.URL;
 import java.net.URLConnection;
 import java.net.URLStreamHandlerFactory;
 import java.util.Collection;
 import java.util.Collections;
 import java.util.Date;
 import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.Executor;
 import java.util.regex.Pattern;
 
+import javax.net.ssl.HttpsURLConnection;
+
 /**
  * An engine to process {@link UrlRequest}s, which uses the best HTTP stack
  * available on the current platform.
  */
 public abstract class CronetEngine {
     /**
      * A builder for {@link CronetEngine}s, which allows runtime configuration of
      * {@code CronetEngine}. Configuration options are set on the builder and
      * then {@link #build} is called to create the {@code CronetEngine}.
      */
@@ skipping 148 matching lines @@
          * @param value {@code true} makes the resulting {@link CronetEngine}
          *              use an implementation based on the system's
          *              {@link java.net.HttpURLConnection} implementation
          *              without trying to load the native implementation.
          *              {@code false} makes the resulting {@code CronetEngine}
          *              use the native implementation, or if that fails to load,
          *              falls back to an implementation based on the system's
          *              {@link java.net.HttpURLConnection} implementation.
          * @return the builder to facilitate chaining.
          * @deprecated Not supported by the new API.
+         * @hide
          */
         @Deprecated
         public Builder enableLegacyMode(boolean value) {
             mLegacyModeEnabled = value;
             return this;
         }
 
         boolean legacyMode() {
             return mLegacyModeEnabled;
         }
@@ skipping 105 matching lines @@
          * Overrides
          * <a href="https://developer.chrome.com/multidevice/data-compression">
          * Data Reduction Proxy</a> configuration parameters with a primary
          * proxy name, fallback proxy name, and a secure proxy check URL. Proxies
          * are specified as [scheme://]host[:port]. Used for testing.
          * @param primaryProxy the primary data reduction proxy to use.
          * @param fallbackProxy a fallback data reduction proxy to use.
          * @param secureProxyCheckUrl a URL to fetch to determine if using a secure
          * proxy is allowed.
          * @return the builder to facilitate chaining.
-         * @deprecated Marked as deprecated because @hide doesn't properly hide but
-         *         javadocs are built with nodeprecated="yes".
+         * @hide as it's a prototype.
          */
-        @Deprecated
-        @SuppressWarnings("DepAnn")
         public Builder setDataReductionProxyOptions(
                 String primaryProxy, String fallbackProxy, String secureProxyCheckUrl) {
             if (primaryProxy.isEmpty() || fallbackProxy.isEmpty()
                     || secureProxyCheckUrl.isEmpty()) {
                 throw new IllegalArgumentException(
                         "Primary and fallback proxies and check url must be set");
             }
             mDataReductionProxyPrimaryProxy = primaryProxy;
             mDataReductionProxyFallbackProxy = fallbackProxy;
             mDataReductionProxySecureProxyCheckUrl = secureProxyCheckUrl;
             return this;
         }
 
         String dataReductionProxyPrimaryProxy() {
             return mDataReductionProxyPrimaryProxy;
         }
 
         String dataReductionProxyFallbackProxy() {
             return mDataReductionProxyFallbackProxy;
         }
 
         String dataReductionProxySecureProxyCheckUrl() {
             return mDataReductionProxySecureProxyCheckUrl;
         }
 
-        /** @deprecated not really deprecated but hidden. */
+        /** @hide */
         @IntDef({
                 HTTP_CACHE_DISABLED, HTTP_CACHE_IN_MEMORY, HTTP_CACHE_DISK_NO_HTTP, HTTP_CACHE_DISK,
         })
         @Retention(RetentionPolicy.SOURCE)
-        @SuppressWarnings("DepAnn")
         public @interface HttpCacheSetting {}
 
         /**
          * Setting to disable HTTP cache. Some data may still be temporarily stored in memory.
          * Passed to {@link #enableHttpCache}.
          */
         public static final int HTTP_CACHE_DISABLED = 0;
 
         /**
          * Setting to enable in-memory HTTP cache, including HTTP data.
@@ skipping 258 matching lines @@
      * and causing exceptions during shutdown. Request is given medium priority,
      * see {@link UrlRequest.Builder#REQUEST_PRIORITY_MEDIUM}. To specify other
      * priorities see {@link #createRequest(String, UrlRequest.Callback,
      * Executor, int priority)}.
      *
      * @param url {@link URL} for the request.
      * @param callback callback object that gets invoked on different events.
      * @param executor {@link Executor} on which all callbacks will be invoked.
      * @return new request.
      * @deprecated Use {@link UrlRequest.Builder#build}.
+     * @hide
      */
     @Deprecated
     public final UrlRequest createRequest(
             String url, UrlRequest.Callback callback, Executor executor) {
         return createRequest(url, callback, executor, UrlRequest.Builder.REQUEST_PRIORITY_MEDIUM);
     }
 
     /**
      * Creates a {@link UrlRequest} object. All callbacks will
      * be called on {@code executor}'s thread. {@code executor} must not run
      * tasks on the current thread to prevent blocking networking operations
      * and causing exceptions during shutdown.
      *
      * @param url {@link URL} for the request.
      * @param callback callback object that gets invoked on different events.
      * @param executor {@link Executor} on which all callbacks will be invoked.
      * @param priority priority of the request which should be one of the
      *         {@link UrlRequest.Builder#REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*}
      *         values.
      * @return new request.
      * @deprecated Use {@link UrlRequest.Builder#build}.
+     * @hide
      */
     @Deprecated
     public final UrlRequest createRequest(String url, UrlRequest.Callback callback,
             Executor executor, @UrlRequest.Builder.RequestPriority int priority) {
         return createRequest(url, callback, executor, priority, Collections.emptyList());
     }
 
     /**
      * Creates a {@link UrlRequest} object. All callbacks will
      * be called on {@code executor}'s thread. {@code executor} must not run
      * tasks on the current thread to prevent blocking networking operations
      * and causing exceptions during shutdown.
      *
      * @param url {@link URL} for the request.
      * @param callback callback object that gets invoked on different events.
      * @param executor {@link Executor} on which all callbacks will be invoked.
      * @param priority priority of the request which should be one of the
      *         {@link UrlRequest.Builder#REQUEST_PRIORITY_IDLE REQUEST_PRIORITY_*}
      *         values.
      * @param requestAnnotations Objects to pass on to {@link CronetEngine.RequestFinishedListener}.
      * @return new request.
+     * @deprecated Use {@link UrlRequest.Builder#build}.
+     * @hide as it references hidden CronetEngine.RequestFinishedListener
      */
+    @Deprecated
     protected abstract UrlRequest createRequest(String url, UrlRequest.Callback callback,
             Executor executor, int priority, Collection<Object> requestAnnotations);
 
     /**
      * Creates a {@link BidirectionalStream} object. {@code callback} methods will
      * be invoked on {@code executor}. {@code executor} must not run
      * tasks on the current thread to prevent blocking networking operations
      * and causing exceptions during shutdown.
      *
      * @param url the URL for the stream
@@ skipping 79 matching lines @@
      * 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,
      * listeners of RTT and throughput can be added with
      * {@link #addRttListener} and {@link #addThroughputListener} and
      * removed with {@link #removeRttListener} and
      * {@link #removeThroughputListener}. The estimator uses memory and CPU
      * only when enabled.
      * @param executor an executor that will be used to notified all
      *            added RTT and throughput listeners.
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated public abstract void enableNetworkQualityEstimator(Executor executor);
+    public abstract void enableNetworkQualityEstimator(Executor executor);
 
     /**
      * Enables the network quality estimator for testing. This must be called
      * before round trip time and throughput listeners 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
      *            listeners will be called.
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated
     abstract void enableNetworkQualityEstimatorForTesting(
             boolean useLocalHostRequests, boolean useSmallerResponses, Executor executor);
 
     /**
      * Registers a listener that gets called whenever the network quality
      * estimator witnesses a sample round trip time. This must be called
      * after {@link #enableNetworkQualityEstimator}, and with throw an
      * exception otherwise. Round trip times may be recorded at various layers
      * of the network stack, including TCP, QUIC, and at the URL request layer.
      * The listener is called on the {@link java.util.concurrent.Executor} that
      * is passed to {@link #enableNetworkQualityEstimator}.
      * @param listener the listener of round trip times.
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated public abstract void addRttListener(NetworkQualityRttListener listener);
+    public abstract void addRttListener(NetworkQualityRttListener listener);
 
     /**
      * Removes a listener of round trip times if previously registered with
      * {@link #addRttListener}. This should be called after a
      * {@link NetworkQualityRttListener} is added in order to stop receiving
      * observations.
      * @param listener the listener of round trip times.
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated public abstract void removeRttListener(NetworkQualityRttListener listener);
+    public abstract void removeRttListener(NetworkQualityRttListener listener);
 
     /**
      * Registers a listener 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 listener
      * is called on the {@link java.util.concurrent.Executor} that is passed to
      * {@link #enableNetworkQualityEstimator}.
      * @param listener the listener of throughput.
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated
     public abstract void addThroughputListener(NetworkQualityThroughputListener listener);
 
     /**
      * Removes a listener of throughput. This should be called after a
      * {@link NetworkQualityThroughputListener} is added with
      * {@link #addThroughputListener} in order to stop receiving observations.
      * @param listener the listener of throughput.
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated
     public abstract void removeThroughputListener(NetworkQualityThroughputListener listener);
 
     /**
      * Establishes a new connection to the resource specified by the {@link URL} {@code url}.
      * <p>
      * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation is subject to certain
      * limitations, see {@link #createURLStreamHandlerFactory} for details.
      *
      * @param url URL of resource to connect to.
      * @return an {@link java.net.HttpURLConnection} instance implemented by this CronetEngine.
      * @throws IOException if an error occurs while opening the connection.
      */
     public abstract URLConnection openConnection(URL url) throws IOException;
 
     /**
      * Establishes a new connection to the resource specified by the {@link URL} {@code url}
      * using the given proxy.
      * <p>
      * <b>Note:</b> Cronet's {@link java.net.HttpURLConnection} implementation is subject to certain
      * limitations, see {@link #createURLStreamHandlerFactory} for details.
      *
      * @param url URL of resource to connect to.
      * @param proxy proxy to use when establishing connection.
      * @return an {@link java.net.HttpURLConnection} instance implemented by this CronetEngine.
      * @throws IOException if an error occurs while opening the connection.
-     * @deprecated Marked as deprecated because @hide doesn't properly hide but
-     *         javadocs are built with nodeprecated="yes".
-     *         TODO(pauljensen): Expose once implemented, http://crbug.com/418111
+     * @hide TODO(pauljensen): Expose once implemented, http://crbug.com/418111
      */
-    @Deprecated
-    @SuppressWarnings("DepAnn")
     public abstract URLConnection openConnection(URL url, Proxy proxy) throws IOException;
 
     /**
      * Creates a {@link URLStreamHandlerFactory} to handle HTTP and HTTPS
      * traffic. An instance of this class can be installed via
      * {@link URL#setURLStreamHandlerFactory} thus using this CronetEngine by default for
      * all requests created via {@link URL#openConnection}.
      * <p>
      * Cronet does not use certain HTTP features provided via the system:
      * <ul>
      * <li>the HTTP cache installed via
-     *     {@link android.net.http.HttpResponseCache#install(java.io.File, long)
-     *            HttpResponseCache.install()}</li>
+     *     {@link HttpResponseCache#install(java.io.File, long) HttpResponseCache.install()}</li>
      * <li>the HTTP authentication method installed via
      *     {@link java.net.Authenticator#setDefault}</li>
      * <li>the HTTP cookie storage installed via {@link java.net.CookieHandler#setDefault}</li>
      * </ul>
      * <p>
      * While Cronet supports and encourages requests using the HTTPS protocol,
      * Cronet does not provide support for the
-     * {@link javax.net.ssl.HttpsURLConnection} API. This lack of support also
+     * {@link HttpsURLConnection} API. This lack of support also
      * includes not using certain HTTPS features provided via the system:
      * <ul>
      * <li>the HTTPS hostname verifier installed via {@link
-     *   javax.net.ssl.HttpsURLConnection#setDefaultHostnameVerifier(javax.net.ssl.HostnameVerifier)
+     *   HttpsURLConnection#setDefaultHostnameVerifier(javax.net.ssl.HostnameVerifier)
      *     HttpsURLConnection.setDefaultHostnameVerifier()}</li>
      * <li>the HTTPS socket factory installed via {@link
-     *   javax.net.ssl.HttpsURLConnection#setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory)
+     *   HttpsURLConnection#setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory)
      *     HttpsURLConnection.setDefaultSSLSocketFactory()}</li>
      * </ul>
      *
      * @return an {@link URLStreamHandlerFactory} instance implemented by this
      *         CronetEngine.
      */
     public abstract URLStreamHandlerFactory createURLStreamHandlerFactory();
 
     /**
      * Creates a {@link CronetEngine} with the given {@link Builder}.
      *
      * @param builder builder to used for creating the CronetEngine instance.
      * @return the created CronetEngine instance.
      * @deprecated Use {@link CronetEngine.Builder}.
+     * @hide
      */
     @Deprecated
     public static CronetEngine createContext(Builder builder) {
         CronetEngine cronetEngine = null;
         if (builder.getUserAgent() == null) {
             builder.setUserAgent(builder.getDefaultUserAgent());
         }
         if (!builder.legacyMode()) {
             cronetEngine = createCronetEngine(builder);
         }
@@ skipping 29 matching lines @@
      * Registers a listener that gets called after the end of each request with the request info.
      *
      * <p>This must be called after {@link #enableNetworkQualityEstimator} and will throw an
      * exception otherwise.
      *
      * <p>The listener is called on the {@link java.util.concurrent.Executor} that
      * is passed to {@link #enableNetworkQualityEstimator}.
      *
      * @param listener the listener for finished requests.
      *
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated public abstract void addRequestFinishedListener(RequestFinishedListener listener);
+    public abstract void addRequestFinishedListener(RequestFinishedListener listener);
 
     /**
      * Removes a finished request listener.
      *
      * @param listener the listener to remove.
      *
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide it's a prototype.
      */
-    @Deprecated
     public abstract void removeRequestFinishedListener(RequestFinishedListener listener);
 
     /**
      * Information about a finished request. Passed to {@link RequestFinishedListener}.
      *
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated
     public static final class UrlRequestInfo {
         private final String mUrl;
         private final Collection<Object> mAnnotations;
         private final UrlRequestMetrics mMetrics;
         @Nullable private final UrlResponseInfo mResponseInfo;
 
         UrlRequestInfo(String url, Collection<Object> annotations, UrlRequestMetrics metrics,
                 @Nullable UrlResponseInfo responseInfo) {
             mUrl = url;
             mAnnotations = annotations;
@@ skipping 37 matching lines @@
         public UrlResponseInfo getResponseInfo() {
             return mResponseInfo;
         }
     }
 
     /**
      * Metrics collected for a single request.
      *
      * <p>Must call {@link #enableNetworkQualityEstimator} to enable request metrics collection.
      *
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated
     public static final class UrlRequestMetrics {
         @Nullable private final Long mTtfbMs;
         @Nullable private final Long mTotalTimeMs;
         @Nullable private final Long mSentBytesCount;
         @Nullable private final Long mReceivedBytesCount;
 
         public UrlRequestMetrics(@Nullable Long ttfbMs, @Nullable Long totalTimeMs,
                 @Nullable Long sentBytesCount, @Nullable Long receivedBytesCount) {
             mTtfbMs = ttfbMs;
             mTotalTimeMs = totalTimeMs;
@@ skipping 32 matching lines @@
          */
         @Nullable
         public Long getReceivedBytesCount() {
             return mReceivedBytesCount;
         }
     }
 
     /**
      * Interface to listen for finished requests that were created via this CronetEngine instance.
      *
-     * @deprecated not really deprecated but hidden for now as it's a prototype.
+     * @hide as it's a prototype.
      */
-    @Deprecated
     public interface RequestFinishedListener { // TODO(klm): Add a convenience abstract class.
         /**
          * Invoked with request info.
          * @param requestInfo {@link UrlRequestInfo} for finished request.
          */
         void onRequestFinished(UrlRequestInfo requestInfo);
     }
 }