Prepare comments and annotations for OverlayManager public API
This patch adds the following items.
* OverlayManager class comments.
* Move the class comments related to OverlayManagerService to @hide
constructor
* Replace @link with @code in comments because of linking to @hide API
* add @SuppressLint("ReferencesHidden") for APIs will be public API
* Add @see for relevant APIs
Bug: 205919743
Test: make update-api ; make
Test: make online-sdk-docs offline-sdk-docs
Test: atest \
OverlayHostTests \
OverlayDeviceTests \
SelfTargetingOverlayDeviceTests \
OverlayRemountedTest \
FrameworksServicesTests:com.android.server.om \
CtsContentTestCases:android.content.om.cts \
idmap2_tests
Change-Id: I0ea9a73e61ac4e435f1ebbaa5bd65bdfe4bc9d25
diff --git a/core/java/android/content/om/OverlayManager.java b/core/java/android/content/om/OverlayManager.java
index 899e356..7803cb8 100644
--- a/core/java/android/content/om/OverlayManager.java
+++ b/core/java/android/content/om/OverlayManager.java
@@ -20,6 +20,7 @@
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.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.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 @@
/**
* 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 @@
/**
* 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 @@
* 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.
*