1/*
2 * Copyright 2017 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.webkit;
18
19import android.annotation.CallbackExecutor;
20import android.annotation.NonNull;
21import android.annotation.Nullable;
22
23import java.io.OutputStream;
24import java.util.concurrent.Executor;
25
26/**
27 * Manages tracing of WebViews. In particular provides functionality for the app
28 * to enable/disable tracing of parts of code and to collect tracing data.
29 * This is useful for profiling performance issues, debugging and memory usage
30 * analysis in production and real life scenarios.
31 * <p>
32 * The resulting trace data is sent back as a byte sequence in json format. This
33 * file can be loaded in "chrome://tracing" for further analysis.
34 * <p>
35 * Example usage:
36 * <pre class="prettyprint">
37 * TracingController tracingController = TracingController.getInstance();
38 * tracingController.start(new TracingConfig.Builder()
39 *                  .addCategories(CATEGORIES_WEB_DEVELOPER).build());
40 * ...
41 * tracingController.stop(new FileOutputStream("trace.json"),
42 *                        Executors.newSingleThreadExecutor());
43 * </pre></p>
44 */
45public abstract class TracingController {
46
47    /**
48     * Returns the default TracingController instance. At present there is
49     * only one TracingController instance for all WebView instances,
50     * however this restriction may be relaxed in a future Android release.
51     *
52     * @return The default TracingController instance.
53     */
54    @NonNull
55    public static TracingController getInstance() {
56        return WebViewFactory.getProvider().getTracingController();
57    }
58
59    /**
60     * Starts tracing all webviews. Depending on the trace mode in traceConfig
61     * specifies how the trace events are recorded.
62     *
63     * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL} and
64     * {@link TracingConfig#RECORD_CONTINUOUSLY} the events are recorded
65     * using an internal buffer and flushed to the outputStream when
66     * {@link #stop(OutputStream, Executor)} is called.
67     *
68     * @param tracingConfig Configuration options to use for tracing.
69     * @throws IllegalStateException If the system is already tracing.
70     * @throws IllegalArgumentException If the configuration is invalid (e.g.
71     *         invalid category pattern or invalid tracing mode).
72     */
73    public abstract void start(@NonNull TracingConfig tracingConfig);
74
75    /**
76     * Stops tracing and flushes tracing data to the specified outputStream.
77     *
78     * The data is sent to the specified output stream in json format typically
79     * in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion
80     * the {@link java.io.OutputStream#close()} method is called.
81     *
82     * @param outputStream The output stream the tracing data will be sent to. If null
83     *                     the tracing data will be discarded.
84     * @param executor The {@link java.util.concurrent.Executor} on which the
85     *        outputStream {@link java.io.OutputStream#write(byte[])} and
86     *        {@link java.io.OutputStream#close()} methods will be invoked.
87     * @return False if the WebView framework was not tracing at the time of the call,
88     *         true otherwise.
89     */
90    public abstract boolean stop(@Nullable OutputStream outputStream,
91            @NonNull @CallbackExecutor Executor executor);
92
93    /**
94     * Returns whether the WebView framework is tracing.
95     *
96     * @return True if tracing is enabled.
97     */
98    public abstract boolean isTracing();
99
100}
101