From d9c0b685fa8fe1d7a6873d3bab90688befa060a9 Mon Sep 17 00:00:00 2001 From: felkachang Date: Tue, 6 Dec 2022 08:19:53 +0000 Subject: [PATCH] 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 --- .../android/content/om/OverlayManager.java | 88 +++++++++++-------- 1 file changed, 53 insertions(+), 35 deletions(-) diff --git a/core/java/android/content/om/OverlayManager.java b/core/java/android/content/om/OverlayManager.java index 899e356989050..7803cb8829178 100644 --- a/core/java/android/content/om/OverlayManager.java +++ b/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). * - *

Users of this API must be actors of any overlays they desire to change the state of.

+ *

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}. * - *

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.

- * - *

Actors are specified as part of the overlayable definition. - * - * 

{@code
- * 
- * }

- * - *

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.

- * - * 
{@code
- * 
- * }

- * - *

An actor can manipulate a particular overlay if any of the following is true: *

+ *
  • register overlays + *
  • unregister overlays + *
  • execute multiple operations in one commitment by calling {@link + * OverlayManagerTransaction#commit()} + * * + * @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. + *

    Users of this API must be actors of any overlays they desire to change the state of. + * + *

    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. + * + *

    Actors are specified as part of the overlayable definition. + * + * 

    {@code
+     * 
+     * }

    + * + *

    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. + * + * 

    {@code
+     * 
+     * }

    + * + *

    An actor can manipulate a particular overlay if any of the following is true: + *

    + * * @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. *