Merge "Prepare comments and annotations for OverlayManager public API"

core/java/android/content/om/OverlayManager.java

@@ -20,6 +20,7 @@ import android.annotation.NonNull;
 import android.annotation.NonUiContext;
 import android.annotation.Nullable;
 import android.annotation.RequiresPermission;
+import android.annotation.SuppressLint;
 import android.annotation.SystemApi;
 import android.annotation.SystemService;
 import android.compat.Compatibility;
@@ -28,7 +29,6 @@ import android.compat.annotation.EnabledSince;
 import android.content.Context;
 import android.content.pm.PackageManager;
 import android.os.Build;
-import android.os.Process;
 import android.os.RemoteException;
 import android.os.ServiceManager;
 import android.os.UserHandle;
@@ -39,40 +39,21 @@ import java.io.IOException;
 import java.util.List;
 
 /**
- * Updates OverlayManager state; gets information about installed overlay packages.
+ * OverlayManager gives apps the ability to create an {@link OverlayManagerTransaction} to
+ * maintain the overlays and list the registered fabricated runtime resources overlays(FRROs).
  *
- * <p>Users of this API must be actors of any overlays they desire to change the state of.</p>
+ * <p>OverlayManager returns the list of overlays to the app calling {@link
+ * #getOverlayInfosForTarget(String)}. The app starts an {@link OverlayManagerTransaction} to manage
+ * the overlays. The app can achieve the following by using {@link OverlayManagerTransaction}.
  *
- * <p>An actor is a package responsible for managing the state of overlays targeting overlayables
- * that specify the actor. For example, an actor may enable or disable an overlay or otherwise
- * change its state.</p>
- *
- * <p>Actors are specified as part of the overlayable definition.
- *
- * <pre>{@code
- * <overlayable name="OverlayableResourcesName" actor="overlay://namespace/actorName">
- * }</pre></p>
- *
- * <p>Actors are defined through SystemConfig. Only system packages can be used.
- * The namespace "android" is reserved for use by AOSP and any "android" definitions must
- * have an implementation on device that fulfill their intended functionality.</p>
- *
- * <pre>{@code
- * <named-actor
- *     namespace="namespace"
- *     name="actorName"
- *     package="com.example.pkg"
- *     />
- * }</pre></p>
- *
- * <p>An actor can manipulate a particular overlay if any of the following is true:
  * <ul>
- * <li>its UID is {@link Process#ROOT_UID}, {@link Process#SYSTEM_UID}</li>
- * <li>it is the target of the overlay package</li>
- * <li>it has the CHANGE_OVERLAY_PACKAGES permission and the target does not specify an actor</li>
- * <li>it is the actor specified by the overlayable</li>
- * </ul></p>
+ *   <li>register overlays
+ *   <li>unregister overlays
+ *   <li>execute multiple operations in one commitment by calling {@link
+ *       OverlayManagerTransaction#commit()}
+ * </ul>
  *
+ * @see OverlayManagerTransaction
  * @hide
  */
 @SystemApi
@@ -85,7 +66,7 @@ public class OverlayManager {
 
     /**
      * Pre R a {@link java.lang.SecurityException} would only be thrown by setEnabled APIs (e
-     * .g. {@link #setEnabled(String, boolean, UserHandle)}) for a permission error.
+     * .g. {@code #setEnabled(String, boolean, UserHandle)}) for a permission error.
      * Since R this no longer holds true, and {@link java.lang.SecurityException} can be
      * thrown for any number of reasons, none of which are exposed to the caller.
      *
@@ -115,19 +96,56 @@ public class OverlayManager {
     /**
      * Creates a new instance.
      *
+     * Updates OverlayManager state; gets information about installed overlay packages.
+     * <p>Users of this API must be actors of any overlays they desire to change the state of.
+     *
+     * <p>An actor is a package responsible for managing the state of overlays targeting
+     * overlayables that specify the actor. For example, an actor may enable or disable an overlay
+     * or otherwise change its state.
+     *
+     * <p>Actors are specified as part of the overlayable definition.
+     *
+     * <pre>{@code
+     * <overlayable name="OverlayableResourcesName" actor="overlay://namespace/actorName">
+     * }</pre></p>
+     *
+     * <p>Actors are defined through {@code com.android.server.SystemConfig}. Only system packages
+     * can be used. The namespace "android" is reserved for use by AOSP and any "android"
+     * definitions must have an implementation on device that fulfill their intended functionality.
+     *
+     * <pre>{@code
+     * <named-actor
+     *     namespace="namespace"
+     *     name="actorName"
+     *     package="com.example.pkg"
+     *     />
+     * }</pre></p>
+     *
+     * <p>An actor can manipulate a particular overlay if any of the following is true:
+     * <ul>
+     * <li>its UID is {@link android.os.Process#ROOT_UID}, {@link android.os.Process#SYSTEM_UID}
+     * </li>
+     * <li>it is the target of the overlay package</li>
+     * <li>it has the CHANGE_OVERLAY_PACKAGES permission and the target does not specify an actor
+     * </li>
+     * <li>it is the actor specified by the overlayable</li>
+     * </ul></p>
+     *
      * @param context The current context in which to operate.
      * @param service The backing system service.
      *
      * @hide
      */
-    public OverlayManager(Context context, IOverlayManager service) {
+    @SuppressLint("ReferencesHidden")
+    public OverlayManager(@NonNull Context context, @Nullable IOverlayManager service) {
         mContext = context;
         mService = service;
         mOverlayManagerImpl = new OverlayManagerImpl(context);
     }
 
     /** @hide */
-    public OverlayManager(Context context) {
+    @SuppressLint("ReferencesHidden")
+    public OverlayManager(@NonNull Context context) {
         this(context, IOverlayManager.Stub.asInterface(
             ServiceManager.getService(Context.OVERLAY_SERVICE)));
     }
@@ -137,7 +155,7 @@ public class OverlayManager {
      * target package and category are disabled.
      *
      * If a set of overlay packages share the same category, single call to this method is
-     * equivalent to multiple calls to {@link #setEnabled(String, boolean, UserHandle)}.
+     * equivalent to multiple calls to {@code #setEnabled(String, boolean, UserHandle)}.
      *
      * The caller must pass the actor requirements specified in the class comment.
      *