| /* |
| * Copyright 2018 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package androidx.webkit; |
| |
| import android.content.Context; |
| |
| import androidx.annotation.NonNull; |
| import androidx.annotation.Nullable; |
| import androidx.annotation.RequiresFeature; |
| import androidx.annotation.RestrictTo; |
| import androidx.webkit.internal.TracingControllerImpl; |
| |
| import java.io.OutputStream; |
| import java.util.concurrent.Executor; |
| |
| /** |
| * Manages tracing of WebViews. In particular provides functionality for the app |
| * to enable/disable tracing of parts of code and to collect tracing data. |
| * This is useful for profiling performance issues, debugging and memory usage |
| * analysis in production and real life scenarios. |
| * <p> |
| * The resulting trace data is sent back as a byte sequence in json format. This |
| * file can be loaded in "chrome://tracing" for further analysis. |
| * <p> |
| * Example usage: |
| * <pre class="prettyprint"> |
| * TracingController tracingController = TracingController.getInstance(); |
| * tracingController.start(new TracingConfig.Builder() |
| * .addCategories(CATEGORIES_WEB_DEVELOPER).build()); |
| * ... |
| * tracingController.stop(new FileOutputStream("trace.json"), |
| * Executors.newSingleThreadExecutor()); |
| * </pre> |
| */ |
| public abstract class TracingController { |
| /** |
| * |
| * @hide Don't allow apps to sub-class this class. |
| */ |
| @RestrictTo(RestrictTo.Scope.LIBRARY) |
| public TracingController() {} |
| |
| /** |
| * Returns the default {@link TracingController} instance. At present there is |
| * only one TracingController instance for all WebView instances. |
| * |
| * <p> |
| * This method should only be called if {@link WebViewFeature#isFeatureSupported(String)} |
| * returns {@code true} for {@link WebViewFeature#TRACING_CONTROLLER_BASIC_USAGE}. |
| * |
| */ |
| @NonNull |
| @RequiresFeature(name = WebViewFeature.TRACING_CONTROLLER_BASIC_USAGE, |
| enforcement = "androidx.webkit.WebViewFeature#isFeatureSupported") |
| public static TracingController getInstance() { |
| return LAZY_HOLDER.INSTANCE; |
| } |
| |
| private static class LAZY_HOLDER { |
| static final TracingController INSTANCE = new TracingControllerImpl(); |
| } |
| |
| /** |
| * Starts tracing all webviews. Depending on the trace mode in traceConfig |
| * specifies how the trace events are recorded. |
| * |
| * <p> |
| * For tracing modes {@link android.webkit.TracingConfig#RECORD_UNTIL_FULL} and |
| * {@link android.webkit.TracingConfig#RECORD_CONTINUOUSLY} the events are recorded |
| * using an internal buffer and flushed to the outputStream when |
| * {@link #stop(OutputStream, Executor)} is called. |
| * |
| * <p> |
| * This method should only be called if {@link WebViewFeature#isFeatureSupported(String)} |
| * returns {@code true} for {@link WebViewFeature#TRACING_CONTROLLER_BASIC_USAGE}. |
| * |
| * @param tracingConfig Configuration options to use for tracing. |
| * |
| * @throws IllegalStateException If the system is already tracing. |
| * @throws IllegalArgumentException If the configuration is invalid (e.g. |
| * invalid category pattern or invalid tracing mode). |
| */ |
| public abstract void start(@NonNull TracingConfig tracingConfig); |
| |
| /** |
| * Stops tracing and flushes tracing data to the specified outputStream. |
| * |
| * The data is sent to the specified output stream in json format typically in chunks |
| * by invoking {@link OutputStream#write(byte[])}. |
| * On completion the {@link OutputStream#close()} method is called. |
| * |
| * <p> |
| * This method should only be called if {@link WebViewFeature#isFeatureSupported(String)} |
| * returns {@code true} for {@link WebViewFeature#TRACING_CONTROLLER_BASIC_USAGE}. |
| * |
| * @param outputStream The output stream the tracing data will be sent to. |
| * If {@code null} the tracing data will be discarded. |
| * @param executor The Executor on which the outputStream {@link OutputStream#write(byte[])} and |
| * {@link OutputStream#close()} methods will be invoked. |
| * |
| * Callback and listener events are dispatched through this Executor, |
| * providing an easy way to control which thread is used. |
| * To dispatch events through the main thread of your application, |
| * you can use {@link Context#getMainExecutor()}. |
| * To dispatch events through a shared thread pool, |
| * you can use {@link android.os.AsyncTask#THREAD_POOL_EXECUTOR}. |
| * |
| * @return {@code false} if the WebView framework was not tracing at the time of the call, |
| * {@code true} otherwise. |
| */ |
| public abstract boolean stop(@Nullable OutputStream outputStream, @NonNull Executor executor); |
| |
| /** |
| * Returns whether the WebView framework is tracing. |
| * |
| * @return True if tracing is enabled. |
| */ |
| public abstract boolean isTracing(); |
| } |