content: /*
   * Copyright (C) 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 com.android.server.wm;
  
  import android.annotation.IntDef;
  import android.annotation.NonNull;
  import android.annotation.Nullable;
  import android.content.Intent;
  
  import java.lang.annotation.Retention;
  import java.lang.annotation.RetentionPolicy;
  
  /**
   * Observe activity manager launch sequences.
   *
   * The activity manager can have at most 1 concurrent launch sequences. Calls to this interface
   * are ordered by a happens-before relation for each defined state transition (see below).
   *
   * When a new launch sequence is made, that sequence is in the {@code INTENT_STARTED} state which
   * is communicated by the {@link #onIntentStarted} callback. This is a transient state.
   *
   * The intent can fail to launch the activity, in which case the sequence's state transitions to
   * {@code INTENT_FAILED} via {@link #onIntentFailed}. This is a terminal state.
   *
   * If an activity is successfully started, the launch sequence's state will transition into
   * {@code STARTED} via {@link #onActivityLaunched}. This is a transient state.
   *
   * It must then transition to either {@code CANCELLED} with {@link #onActivityLaunchCancelled}
   * or into {@code FINISHED} with {@link #onActivityLaunchFinished}. These are terminal states.
   *
   * Note that the {@code ActivityRecordProto} provided as a parameter to some state transitions isn't
   * necessarily the same within a single launch sequence: it is only the top-most activity at the
   * time (if any). Trampoline activities coalesce several activity starts into a single launch
   * sequence.
   *
   * Upon reaching a terminal state, it is considered that there are no active launch sequences
   * until a subsequent transition into {@code INTENT_STARTED} initiates a new launch sequence.
   *
   * <pre>
   *        ┌⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯┐     ┌⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯┐     ╔══════════════════════════╗
   *    ╴╴▶ ⋮ INTENT_STARTED ⋮ ──▶ ⋮     ACTIVITY_LAUNCHED     ⋮ ──▶ ║ ACTIVITY_LAUNCH_FINISHED ║
   *        └⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯┘     └⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯⋯┘     ╚══════════════════════════╝
   *          :                      :
   *          :                      :
   *          ▼                      ▼
   *        ╔════════════════╗     ╔═══════════════════════════╗
   *        ║ INTENT_FAILED  ║     ║ ACTIVITY_LAUNCH_CANCELLED ║
   *        ╚════════════════╝     ╚═══════════════════════════╝
   * </pre>
   */
  public interface ActivityMetricsLaunchObserver {
      /**
       * The 'temperature' at which a launch sequence had started.
       *
       * The lower the temperature the more work has to be done during start-up.
       * A 'cold' temperature means that a new process has been started and likely
       * nothing is cached.
       *
       * A hot temperature means the existing activity is brought to the foreground.
       * It may need to regenerate some objects as a result of {@code onTrimMemory}.
       *
       * A warm temperature is in the middle; an existing process is used, but the activity
       * has to be created from scratch with {@code #onCreate}.
       *
       * @see https://developer.android.com/topic/performance/vitals/launch-time
       */
      @Retention(RetentionPolicy.SOURCE)
      @IntDef({
              TEMPERATURE_COLD,
              TEMPERATURE_WARM,
              TEMPERATURE_HOT
      })
      @interface Temperature {}
  
      /** Cold launch sequence: a new process has started. */
      public static final int TEMPERATURE_COLD = 1;
      /** Warm launch sequence: process reused, but activity has to be created. */
      public static final int TEMPERATURE_WARM = 2;
      /** Hot launch sequence: process reused, activity brought-to-top. */
      public static final int TEMPERATURE_HOT = 3;
  
      /**
       * Typedef marker that a {@code byte[]} actually contains an
       * <a href="proto/android/server/activitymanagerservice.proto">ActivityRecordProto</a>
       * in the protobuf format.
       */
      @Retention(RetentionPolicy.SOURCE)
      @interface ActivityRecordProto {}
  
      /**
       * Notifies the observer that a new launch sequence has begun as a result of a new intent.
       *
       * Once a launch sequence begins, the resolved activity will either subsequently start with
       * {@link #onActivityLaunched} or abort early (for example due to a resolution error or due to
       * a security error) with {@link #onIntentFailed}.
       *
       * Multiple calls to this method cannot occur without first terminating the current
       * launch sequence.
       */
      public void onIntentStarted(@NonNull Intent intent);
  
      /**
       * Notifies the observer that the current launch sequence has failed to launch an activity.
       *
       * This function call terminates the current launch sequence. The next method call, if any,
       * must be {@link #onIntentStarted}.
       *
       * Examples of this happening:
       *  - Failure to resolve to an activity
       *  - Calling package did not have the security permissions to call the requested activity
       *  - Resolved activity was already running and only needed to be brought to the top
       *
       * Multiple calls to this method cannot occur without first terminating the current
       * launch sequence.
       */
      public void onIntentFailed();
  
      /**
       * Notifies the observer that the current launch sequence had begun starting an activity.
       *
       * This is an intermediate state: once an activity begins starting, the entire launch sequence
       * will later terminate by either finishing or cancelling.
       *
       * The initial activity is the first activity to be started as part of a launch sequence:
       * it is represented by {@param activity} However, it isn't
       * necessarily the activity which will be considered as displayed when the activity
       * finishes launching (e.g. {@code activity} in {@link #onActivityLaunchFinished}).
       *
       * Multiple calls to this method cannot occur without first terminating the current
       * launch sequence.
       */
      public void onActivityLaunched(@NonNull @ActivityRecordProto byte[] activity,
                                     @Temperature int temperature);
  
      /**
       * Notifies the observer that the current launch sequence has been aborted.
       *
       * This function call terminates the current launch sequence. The next method call, if any,
       * must be {@link #onIntentStarted}.
       *
       * This can happen for many reasons, for example the user switches away to another app
       * prior to the launch sequence completing, or the application being killed.
       *
       * Multiple calls to this method cannot occur without first terminating the current
       * launch sequence.
       *
       * @param abortingActivity the last activity that had the top-most window during abort
       *                         (this can be {@code null} in rare situations its unknown).
       *
       * @apiNote The aborting activity isn't necessarily the same as the starting activity;
       *          in the case of a trampoline, multiple activities could've been started
       *          and only the latest activity is reported here.
       */
      public void onActivityLaunchCancelled(@Nullable @ActivityRecordProto byte[] abortingActivity);
  
      /**
       * Notifies the observer that the current launch sequence has been successfully finished.
       *
       * This function call terminates the current launch sequence. The next method call, if any,
       * must be {@link #onIntentStarted}.
       *
       * A launch sequence is considered to be successfully finished when a frame is fully
       * drawn for the first time: the top-most activity at the time is what's reported here.
       *
       * @param finalActivity the top-most activity whose windows were first to fully draw
       *
       * Multiple calls to this method cannot occur without first terminating the current
       * launch sequence.
       *
       * @apiNote The finishing activity isn't necessarily the same as the starting activity;
       *          in the case of a trampoline, multiple activities could've been started
       *          and only the latest activity that was top-most during first-frame drawn
       *          is reported here.
       */
      public void onActivityLaunchFinished(@NonNull @ActivityRecordProto byte[] finalActivity);
  }
  