WebView Tracing API: address comments from the API council.

Address comments from the API council regarding the WebView Tracing API.

android.webkit.TracingController:
 * start() throws IllegalStateException if the system is already tracing
   (this is instead of returning false)
 * stop uses Executor instead of Handler
 * removed stop() (the method w/o arguments)
 * renamed stopAndFlush to stop
 * use OutputStream instead of a custom callback interface TracingOutputStream
 * dropped requirement for UI threading
 * updated documentation

android.webkit.TracingFileOutputStream:
 * removed the TracingFileOutputStream file completely (functionality
   replaced by the existing FileOutputStream)

android.webkit.TracingConfig:
 * removed example with CATEGORIES_NONE and “-input,-gpu”.
 * customCategories are List<String> instead of String
 * updated documentation
 * added two more predefined categories: CATEGORIES_ALL,
   CATEGORIES_ANDROID_WEBVIEW
 * some refactoring, added a Builder class
 * ensure that only include category patterns can be specified
 * uniform addCategories interface for construction
 * predefined category sets are a bitmask now

BUG: 71584598,71584599,63750258
Test: CTS
Change-Id: I615ef5f43d26968329182b09e7c26178f1f85ecc

1 files changed, 160 insertions, 99 deletions

diff --git a/core/java/android/webkit/TracingConfig.java b/core/java/android/webkit/TracingConfig.java
index 75e2bf7026c5..68badecaec3a 100644
--- a/core/java/android/webkit/TracingConfig.java
+++ b/core/java/android/webkit/TracingConfig.java
@@ -21,61 +21,76 @@ import android.annotation.NonNull;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.List;
 
 /**
  * Holds tracing configuration information and predefined settings.
  */
 public class TracingConfig {
 
-    private final String mCustomCategoryPattern;
-    private final @PresetCategories int mPresetCategories;
+    private @PredefinedCategories int mPredefinedCategories;
+    private final List<String> mCustomIncludedCategories = new ArrayList<String>();
     private @TracingMode int mTracingMode;
 
     /** @hide */
-    @IntDef({CATEGORIES_NONE, CATEGORIES_WEB_DEVELOPER, CATEGORIES_INPUT_LATENCY,
-            CATEGORIES_RENDERING, CATEGORIES_JAVASCRIPT_AND_RENDERING, CATEGORIES_FRAME_VIEWER})
+    @IntDef(flag = true, value = {CATEGORIES_NONE, CATEGORIES_WEB_DEVELOPER,
+            CATEGORIES_INPUT_LATENCY, CATEGORIES_RENDERING, CATEGORIES_JAVASCRIPT_AND_RENDERING,
+            CATEGORIES_FRAME_VIEWER})
     @Retention(RetentionPolicy.SOURCE)
-    public @interface PresetCategories {}
+    public @interface PredefinedCategories {}
 
     /**
-     * Indicates that there are no preset categories.
+     * Indicates that there are no predefined categories.
      */
-    public static final int CATEGORIES_NONE = -1;
+    public static final int CATEGORIES_NONE = 0;
 
     /**
-     * Predefined categories typically useful for web developers.
+     * Predefined set of categories, includes all categories enabled by default in chromium.
+     * Use with caution: this setting may produce large trace output.
+     */
+    public static final int CATEGORIES_ALL = 1 << 0;
+
+    /**
+     * Predefined set of categories typically useful for analyzing WebViews.
+     * Typically includes android_webview and Java.
+     */
+    public static final int CATEGORIES_ANDROID_WEBVIEW = 1 << 1;
+
+    /**
+     * Predefined set of categories typically useful for web developers.
      * Typically includes blink, compositor, renderer.scheduler and v8 categories.
      */
-    public static final int CATEGORIES_WEB_DEVELOPER = 0;
+    public static final int CATEGORIES_WEB_DEVELOPER = 1 << 2;
 
     /**
-     * Predefined categories for analyzing input latency issues.
+     * Predefined set of categories for analyzing input latency issues.
      * Typically includes input, renderer.scheduler categories.
      */
-    public static final int CATEGORIES_INPUT_LATENCY = 1;
+    public static final int CATEGORIES_INPUT_LATENCY = 1 << 3;
 
     /**
-     * Predefined categories for analyzing rendering issues.
+     * Predefined set of categories for analyzing rendering issues.
      * Typically includes blink, compositor and gpu categories.
      */
-    public static final int CATEGORIES_RENDERING = 2;
+    public static final int CATEGORIES_RENDERING = 1 << 4;
 
     /**
-     * Predefined categories for analyzing javascript and rendering issues.
-     * Typically includes blink, compositor, gpu, renderer.schduler and v8 categories.
+     * Predefined set of categories for analyzing javascript and rendering issues.
+     * Typically includes blink, compositor, gpu, renderer.scheduler and v8 categories.
      */
-    public static final int CATEGORIES_JAVASCRIPT_AND_RENDERING = 3;
+    public static final int CATEGORIES_JAVASCRIPT_AND_RENDERING = 1 << 5;
 
     /**
-     * Predefined categories for studying difficult rendering performance problems.
+     * Predefined set of categories for studying difficult rendering performance problems.
      * Typically includes blink, compositor, gpu, renderer.scheduler, v8 and
      * some other compositor categories which are disabled by default.
      */
-    public static final int CATEGORIES_FRAME_VIEWER = 4;
+    public static final int CATEGORIES_FRAME_VIEWER = 1 << 6;
 
     /** @hide */
-    @IntDef({RECORD_UNTIL_FULL, RECORD_CONTINUOUSLY, RECORD_UNTIL_FULL_LARGE_BUFFER,
-            RECORD_TO_CONSOLE})
+    @IntDef({RECORD_UNTIL_FULL, RECORD_CONTINUOUSLY, RECORD_UNTIL_FULL_LARGE_BUFFER})
     @Retention(RetentionPolicy.SOURCE)
     public @interface TracingMode {}
 
@@ -97,99 +112,38 @@ public class TracingConfig {
 
     /**
      * Record trace events using a larger internal tracing buffer until it is full.
-     * Uses more memory than the other modes and may not be suitable on devices
-     * with smaller RAM. Depending on the implementation typically allows up to
-     * 512 million events to be stored.
+     * Uses significantly more memory than {@link #RECORD_UNTIL_FULL} and may not be
+     * suitable on devices with smaller RAM.
      */
     public static final int RECORD_UNTIL_FULL_LARGE_BUFFER = 2;
 
     /**
-     * Record trace events to console (logcat). The events are discarded and nothing
-     * is sent back to the caller. Uses the least memory as compared to the other modes.
-     */
-    public static final int RECORD_TO_CONSOLE = 3;
-
-    /**
-     * Create config with the preset categories.
-     * <p>
-     * Example:
-     *    TracingConfig(CATEGORIES_WEB_DEVELOPER) -- records trace events from the "web developer"
-     *                                               preset categories.
-     *
-     * @param presetCategories preset categories to use, one of {@link #CATEGORIES_WEB_DEVELOPER},
-     *                    {@link #CATEGORIES_INPUT_LATENCY}, {@link #CATEGORIES_RENDERING},
-     *                    {@link #CATEGORIES_JAVASCRIPT_AND_RENDERING} or
-     *                    {@link #CATEGORIES_FRAME_VIEWER}.
-     *
-     * Note: for specifying custom categories without presets use
-     * {@link #TracingConfig(int, String, int)}.
-     *
+     * @hide
      */
-    public TracingConfig(@PresetCategories int presetCategories) {
-        this(presetCategories, "", RECORD_UNTIL_FULL);
+    public TracingConfig(@PredefinedCategories int predefinedCategories,
+            @NonNull List<String> customIncludedCategories,
+            @TracingMode int tracingMode) {
+        mPredefinedCategories = predefinedCategories;
+        mCustomIncludedCategories.addAll(customIncludedCategories);
+        mTracingMode = tracingMode;
     }
 
     /**
-     * Create a configuration with both preset categories and custom categories.
-     * Also allows to specify the tracing mode.
-     *
-     * Note that the categories are defined by the currently-in-use version of WebView. They live
-     * in chromium code and are not part of the Android API. See
-     * See <a href="https://www.chromium.org/developers/how-tos/trace-event-profiling-tool">
-     * chromium documentation on tracing</a> for more details.
-     *
-     * <p>
-     * Examples:
-     *
-     *  Preset category with a specified trace mode:
-     *    TracingConfig(CATEGORIES_WEB_DEVELOPER, "", RECORD_UNTIL_FULL_LARGE_BUFFER);
-     *  Custom categories:
-     *    TracingConfig(CATEGORIES_NONE, "browser", RECORD_UNTIL_FULL)
-     *      -- records only the trace events from the "browser" category.
-     *    TraceConfig(CATEGORIES_NONE, "-input,-gpu", RECORD_UNTIL_FULL)
-     *      -- records all trace events excluding the events from the "input" and 'gpu' categories.
-     *    TracingConfig(CATEGORIES_NONE, "blink*,devtools*", RECORD_UNTIL_FULL)
-     *      -- records only the trace events matching the "blink*" and "devtools*" patterns
-     *         (e.g. "blink_gc" and "devtools.timeline" categories).
-     *
-     *  Combination of preset and additional custom categories:
-     *    TracingConfig(CATEGORIES_WEB_DEVELOPER, "memory-infra", RECORD_CONTINUOUSLY)
-     *      -- records events from the "web developer" categories and events from the "memory-infra"
-     *         category to understand where memory is being used.
-     *
-     * @param presetCategories preset categories to use, one of {@link #CATEGORIES_WEB_DEVELOPER},
-     *                    {@link #CATEGORIES_INPUT_LATENCY}, {@link #CATEGORIES_RENDERING},
-     *                    {@link #CATEGORIES_JAVASCRIPT_AND_RENDERING} or
-     *                    {@link #CATEGORIES_FRAME_VIEWER}.
-     * @param customCategories a comma-delimited list of category wildcards. A category can
-     *                         have an optional '-' prefix to make it an excluded category.
-     * @param tracingMode tracing mode to use, one of {@link #RECORD_UNTIL_FULL},
-     *                    {@link #RECORD_CONTINUOUSLY}, {@link #RECORD_UNTIL_FULL_LARGE_BUFFER}
-     *                    or {@link #RECORD_TO_CONSOLE}.
-     */
-    public TracingConfig(@PresetCategories int presetCategories,
-            @NonNull String customCategories, @TracingMode int tracingMode) {
-        mPresetCategories = presetCategories;
-        mCustomCategoryPattern = customCategories;
-        mTracingMode = RECORD_UNTIL_FULL;
+     * Returns a bitmask of the predefined categories values of this configuration.
+     */
+    @PredefinedCategories
+    public int getPredefinedCategories() {
+        return mPredefinedCategories;
     }
 
     /**
-     * Returns the custom category pattern for this configuration.
+     * Returns the list of included custom category patterns for this configuration.
      *
-     * @return empty string if no custom category pattern is specified.
+     * @return empty list if no custom category patterns are specified.
      */
     @NonNull
-    public String getCustomCategoryPattern() {
-        return mCustomCategoryPattern;
-    }
-
-    /**
-     * Returns the preset categories value of this configuration.
-     */
-    @PresetCategories
-    public int getPresetCategories() {
-        return mPresetCategories;
+    public List<String> getCustomIncludedCategories() {
+        return mCustomIncludedCategories;
     }
 
     /**
@@ -200,4 +154,111 @@ public class TracingConfig {
         return mTracingMode;
     }
 
+    /**
+     * Builder used to create {@link TracingConfig} objects.
+     *
+     * Examples:
+     *   new TracingConfig.Builder().build()
+     *       -- creates a configuration with default options: {@link #CATEGORIES_NONE},
+     *          {@link #RECORD_UNTIL_FULL}.
+     *   new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER).build()
+     *       -- records trace events from the "web developer" predefined category sets.
+     *   new TracingConfig.Builder().addCategories(CATEGORIES_RENDERING,
+     *                                             CATEGORIES_INPUT_LATENCY).build()
+     *       -- records trace events from the "rendering" and "input latency" predefined
+     *          category sets.
+     *   new TracingConfig.Builder().addCategories("browser").build()
+     *       -- records only the trace events from the "browser" category.
+     *   new TracingConfig.Builder().addCategories("blink*","renderer*").build()
+     *       -- records only the trace events matching the "blink*" and "renderer*" patterns
+     *          (e.g. "blink.animations", "renderer_host" and "renderer.scheduler" categories).
+     *   new TracingConfig.Builder().addCategories(CATEGORIES_WEB_DEVELOPER)
+     *                              .addCategories("disabled-by-default-v8.gc")
+     *                              .setTracingMode(RECORD_CONTINUOUSLY).build()
+     *       -- records events from the "web developer" predefined category set and events from
+     *          the "disabled-by-default-v8.gc" category to understand where garbage collection
+     *          is being triggered. Uses a ring buffer for internal storage during tracing.
+     */
+    public static class Builder {
+        private @PredefinedCategories int mPredefinedCategories = CATEGORIES_NONE;
+        private final List<String> mCustomIncludedCategories = new ArrayList<String>();
+        private @TracingMode int mTracingMode = RECORD_UNTIL_FULL;
+
+        /**
+         * Default constructor for Builder.
+         */
+        public Builder() {}
+
+        /**
+         * Build {@link TracingConfig} using the current settings.
+         */
+        public TracingConfig build() {
+            return new TracingConfig(mPredefinedCategories, mCustomIncludedCategories,
+                    mTracingMode);
+        }
+
+        /**
+         * Adds categories from a predefined set of categories to be included in the trace output.
+         *
+         * @param predefinedCategories list or bitmask of predefined category sets to use:
+         *                    {@link #CATEGORIES_NONE}, {@link #CATEGORIES_ALL},
+         *                    {@link #CATEGORIES_WEB_DEVELOPER}, {@link #CATEGORIES_INPUT_LATENCY},
+         *                    {@link #CATEGORIES_RENDERING},
+         *                    {@link #CATEGORIES_JAVASCRIPT_AND_RENDERING} or
+         *                    {@link #CATEGORIES_FRAME_VIEWER}.
+         * @return The builder to facilitate chaining.
+         */
+        public Builder addCategories(@PredefinedCategories int... predefinedCategories) {
+            for (int categorySet : predefinedCategories) {
+                mPredefinedCategories |= categorySet;
+            }
+            return this;
+        }
+
+        /**
+         * Adds custom categories to be included in trace output.
+         *
+         * Note that the categories are defined by the currently-in-use version of WebView. They
+         * live in chromium code and are not part of the Android API. See
+         * See <a href="https://www.chromium.org/developers/how-tos/trace-event-profiling-tool">
+         * chromium documentation on tracing</a> for more details.
+         *
+         * @param categories a list of category patterns. A category pattern can contain wilcards,
+         *        e.g. "blink*" or full category name e.g. "renderer.scheduler".
+         * @return The builder to facilitate chaining.
+         */
+        public Builder addCategories(String... categories) {
+            for (String category: categories) {
+                mCustomIncludedCategories.add(category);
+            }
+            return this;
+        }
+
+        /**
+         * Adds custom categories to be included in trace output.
+         *
+         * Same as {@link #addCategories(String...)} but allows to pass a Collection as a parameter.
+         *
+         * @param categories a list of category patters.
+         * @return The builder to facilitate chaining.
+         */
+        public Builder addCategories(Collection<String> categories) {
+            mCustomIncludedCategories.addAll(categories);
+            return this;
+        }
+
+        /**
+         * Sets the tracing mode for this configuration.
+         *
+         * @param tracingMode tracing mode to use, one of {@link #RECORD_UNTIL_FULL},
+         *                    {@link #RECORD_CONTINUOUSLY} or
+         *                    {@link #RECORD_UNTIL_FULL_LARGE_BUFFER}.
+         * @return The builder to facilitate chaining.
+         */
+        public Builder setTracingMode(@TracingMode int tracingMode) {
+            mTracingMode = tracingMode;
+            return this;
+        }
+    }
+
 }