Home | History | Annotate | Download | only in webkit 
      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 
     17 package android.webkit;
     18 
     19 import android.annotation.CallbackExecutor;
     20 import android.annotation.NonNull;
     21 import android.annotation.Nullable;
     22 
     23 import java.io.OutputStream;
     24 import 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(TracingConfig.CATEGORIES_WEB_DEVELOPER).build());
     40  * ...
     41  * tracingController.stop(new FileOutputStream("trace.json"),
     42  *                        Executors.newSingleThreadExecutor());
     43  * </pre></p>
     44  */
     45 public abstract class TracingController {
     46     /**
     47      * @deprecated This class should not be constructed by applications, use {@link #getInstance}
     48      * instead to fetch the singleton instance.
     49      */
     50     // TODO(ntfschr): mark this as @SystemApi after a year.
     51     @Deprecated
     52     public TracingController() {}
     53 
     54     /**
     55      * Returns the default TracingController instance. At present there is
     56      * only one TracingController instance for all WebView instances,
     57      * however this restriction may be relaxed in a future Android release.
     58      *
     59      * @return The default TracingController instance.
     60      */
     61     @NonNull
     62     public static TracingController getInstance() {
     63         return WebViewFactory.getProvider().getTracingController();
     64     }
     65 
     66     /**
     67      * Starts tracing all webviews. Depending on the trace mode in traceConfig
     68      * specifies how the trace events are recorded.
     69      *
     70      * For tracing modes {@link TracingConfig#RECORD_UNTIL_FULL} and
     71      * {@link TracingConfig#RECORD_CONTINUOUSLY} the events are recorded
     72      * using an internal buffer and flushed to the outputStream when
     73      * {@link #stop(OutputStream, Executor)} is called.
     74      *
     75      * @param tracingConfig Configuration options to use for tracing.
     76      * @throws IllegalStateException If the system is already tracing.
     77      * @throws IllegalArgumentException If the configuration is invalid (e.g.
     78      *         invalid category pattern or invalid tracing mode).
     79      */
     80     public abstract void start(@NonNull TracingConfig tracingConfig);
     81 
     82     /**
     83      * Stops tracing and flushes tracing data to the specified outputStream.
     84      *
     85      * The data is sent to the specified output stream in json format typically
     86      * in chunks by invoking {@link java.io.OutputStream#write(byte[])}. On completion
     87      * the {@link java.io.OutputStream#close()} method is called.
     88      *
     89      * @param outputStream The output stream the tracing data will be sent to. If null
     90      *                     the tracing data will be discarded.
     91      * @param executor The {@link java.util.concurrent.Executor} on which the
     92      *        outputStream {@link java.io.OutputStream#write(byte[])} and
     93      *        {@link java.io.OutputStream#close()} methods will be invoked.
     94      * @return False if the WebView framework was not tracing at the time of the call,
     95      *         true otherwise.
     96      */
     97     public abstract boolean stop(@Nullable OutputStream outputStream,
     98             @NonNull @CallbackExecutor Executor executor);
     99 
    100     /**
    101      * Returns whether the WebView framework is tracing.
    102      *
    103      * @return True if tracing is enabled.
    104      */
    105     public abstract boolean isTracing();
    106 
    107 }
    108