From eaa0ad10e8047576aa1de969ce0f31ba8a4d6ba5 Mon Sep 17 00:00:00 2001 From: felkachang Date: Wed, 7 Dec 2022 08:00:29 +0000 Subject: Prepare comments and annotations for OverlayInfo & OverlayIdentifier public API This patch doesn't change any logic or data type. It only prepare the comments for public API in OverlayInfo and OverlayIdentifier. In both of OverlayInfo and OverlayIdentifier * Add class comments for self-targeting * Add comments and annotations for the APIs will be public * such as nullability * Add @hide for the APIs not to public * Separate the comments for OverlayManagerService with HTML comments. OverlayInfo * Add @see relevant APIs. OverlayIdentifier * change protected to be /* package-private */ * Make the class definition to be final because of parcelable. 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 \ CtsContentTestCases:android.content.res.loader.cts \ idmap2_tests Change-Id: I5dc4dca33b75bdd382e817803927fa33bdb84667 --- core/api/system-current.txt | 2 +- .../java/android/content/om/OverlayIdentifier.java | 64 +++++++++++++++++----- core/java/android/content/om/OverlayInfo.java | 57 +++++++++++++++---- 3 files changed, 99 insertions(+), 24 deletions(-) diff --git a/core/api/system-current.txt b/core/api/system-current.txt index 9e2f54f310c8..fd28f9767926 100644 --- a/core/api/system-current.txt +++ b/core/api/system-current.txt @@ -3427,7 +3427,7 @@ package android.content.om { method @NonNull public String getTargetPackageName(); method public int getUserId(); method public boolean isEnabled(); - method public void writeToParcel(android.os.Parcel, int); + method public void writeToParcel(@NonNull android.os.Parcel, int); field @NonNull public static final android.os.Parcelable.Creator CREATOR; } diff --git a/core/java/android/content/om/OverlayIdentifier.java b/core/java/android/content/om/OverlayIdentifier.java index 454d0d120f2f..a43091e6d5e2 100644 --- a/core/java/android/content/om/OverlayIdentifier.java +++ b/core/java/android/content/om/OverlayIdentifier.java @@ -27,32 +27,44 @@ import java.util.Objects; /** * A key used to uniquely identify a Runtime Resource Overlay (RRO). + * * - * An overlay always belongs to a package and may optionally have a name associated with it. - * The name helps uniquely identify a particular overlay within a package. - * @hide + *

An overlay always belongs to a package and have a mandatory name associated with it. The name + * helps uniquely identify a particular overlay within a package. + * + * + * + * + * @see OverlayInfo#getOverlayIdentifier() + * @see OverlayManagerTransaction.Builder#unregisterFabricatedOverlay(OverlayIdentifier) */ /** @hide */ @DataClass(genConstructor = false, genBuilder = false, genHiddenBuilder = false, genEqualsHashCode = true, genToString = false) -public class OverlayIdentifier implements Parcelable { +public final class OverlayIdentifier implements Parcelable { /** * The package name containing or owning the overlay. + * + * @hide */ - @Nullable - private final String mPackageName; + @Nullable private final String mPackageName; /** * The unique name within the package of the overlay. + * + * @hide */ - @Nullable - private final String mOverlayName; + @Nullable private final String mOverlayName; /** * Creates an identifier from a package and unique name within the package. * * @param packageName the package containing or owning the overlay * @param overlayName the unique name of the overlay within the package + * @hide */ public OverlayIdentifier(@NonNull String packageName, @Nullable String overlayName) { mPackageName = packageName; @@ -63,18 +75,24 @@ public class OverlayIdentifier implements Parcelable { * Creates an identifier for an overlay without a name. * * @param packageName the package containing or owning the overlay + * @hide */ public OverlayIdentifier(@NonNull String packageName) { mPackageName = packageName; mOverlayName = null; } + /** + * {@inheritDoc} + * @hide + */ @Override public String toString() { return mOverlayName == null ? mPackageName : mPackageName + ":" + mOverlayName; } /** @hide */ + @NonNull public static OverlayIdentifier fromString(@NonNull String text) { final String[] parts = text.split(":", 2); if (parts.length == 2) { @@ -86,7 +104,7 @@ public class OverlayIdentifier implements Parcelable { - // Code below generated by codegen v1.0.22. + // Code below generated by codegen v1.0.23. // // DO NOT MODIFY! // CHECKSTYLE:OFF Generated code @@ -101,6 +119,8 @@ public class OverlayIdentifier implements Parcelable { /** * Retrieves the package name containing or owning the overlay. + * + * @hide */ @DataClass.Generated.Member public @Nullable String getPackageName() { @@ -109,12 +129,18 @@ public class OverlayIdentifier implements Parcelable { /** * Retrieves the unique name within the package of the overlay. + * + * @hide */ @DataClass.Generated.Member public @Nullable String getOverlayName() { return mOverlayName; } + /** + * {@inheritDoc} + * @hide + */ @Override @DataClass.Generated.Member public boolean equals(@Nullable Object o) { @@ -132,6 +158,10 @@ public class OverlayIdentifier implements Parcelable { && Objects.equals(mOverlayName, that.mOverlayName); } + /** + * {@inheritDoc} + * @hide + */ @Override @DataClass.Generated.Member public int hashCode() { @@ -144,6 +174,10 @@ public class OverlayIdentifier implements Parcelable { return _hash; } + /** + * {@inheritDoc} + * @hide + */ @Override @DataClass.Generated.Member public void writeToParcel(@NonNull Parcel dest, int flags) { @@ -158,6 +192,10 @@ public class OverlayIdentifier implements Parcelable { if (mOverlayName != null) dest.writeString(mOverlayName); } + /** + * {@inheritDoc} + * @hide + */ @Override @DataClass.Generated.Member public int describeContents() { return 0; } @@ -165,7 +203,7 @@ public class OverlayIdentifier implements Parcelable { /** @hide */ @SuppressWarnings({"unchecked", "RedundantCast"}) @DataClass.Generated.Member - protected OverlayIdentifier(@NonNull Parcel in) { + /* package-private */ OverlayIdentifier(@NonNull Parcel in) { // You can override field unparcelling by defining methods like: // static FieldType unparcelFieldName(Parcel in) { ... } @@ -194,10 +232,10 @@ public class OverlayIdentifier implements Parcelable { }; @DataClass.Generated( - time = 1612482438728L, - codegenVersion = "1.0.22", + time = 1670404485646L, + codegenVersion = "1.0.23", sourceFile = "frameworks/base/core/java/android/content/om/OverlayIdentifier.java", - inputSignatures = "private final @android.annotation.Nullable java.lang.String mPackageName\nprivate final @android.annotation.Nullable java.lang.String mOverlayName\npublic @java.lang.Override java.lang.String toString()\npublic static android.content.om.OverlayIdentifier fromString(java.lang.String)\nclass OverlayIdentifier extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genConstructor=false, genBuilder=false, genHiddenBuilder=false, genEqualsHashCode=true, genToString=false)") + inputSignatures = "private final @android.annotation.Nullable java.lang.String mPackageName\nprivate final @android.annotation.Nullable java.lang.String mOverlayName\npublic @java.lang.Override java.lang.String toString()\npublic static @android.annotation.NonNull android.content.om.OverlayIdentifier fromString(java.lang.String)\nclass OverlayIdentifier extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genConstructor=false, genBuilder=false, genHiddenBuilder=false, genEqualsHashCode=true, genToString=false)") @Deprecated private void __metadata() {} diff --git a/core/java/android/content/om/OverlayInfo.java b/core/java/android/content/om/OverlayInfo.java index a470de2db8fd..a81d16ab4ca3 100644 --- a/core/java/android/content/om/OverlayInfo.java +++ b/core/java/android/content/om/OverlayInfo.java @@ -33,9 +33,19 @@ import java.lang.annotation.RetentionPolicy; import java.util.Objects; /** + * An immutable information about an overlay. + * + *

Applications calling {@link OverlayManager#getOverlayInfosForTarget(String)} get the + * information list of the registered overlays. Each element in the list presents the information of + * the particular overlay. + * + * + * * + * @see OverlayManager#getOverlayInfosForTarget(String) * @hide */ @SystemApi @@ -174,14 +184,14 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { * * @hide */ - public final String targetOverlayableName; + @Nullable public final String targetOverlayableName; /** * Category of the overlay package * * @hide */ - public final String category; + @Nullable public final String category; /** * Full path to the base APK for this overlay package @@ -272,7 +282,7 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { } /** @hide */ - public OverlayInfo(Parcel source) { + public OverlayInfo(@NonNull Parcel source) { packageName = source.readString(); overlayName = source.readString(); targetPackageName = source.readString(); @@ -299,7 +309,9 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { } /** - * {@inheritDoc} + * Get the overlay name from the registered fabricated overlay. + * + * @return the overlay name * @hide */ @Override @@ -309,7 +321,9 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { } /** - * {@inheritDoc} + * Returns the name of the target overlaid package. + * + * @return the target package name * @hide */ @Override @@ -342,11 +356,13 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { } /** - * {@inheritDoc} + * Return the target overlayable name. + * + * @return the name of the target overlayable resources set * @hide */ - @Override @SystemApi + @Override @Nullable public String getTargetOverlayableName() { return targetOverlayableName; @@ -366,12 +382,18 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { * * @hide */ + @NonNull public String getBaseCodePath() { return baseCodePath; } /** - * {@inheritDoc} + * Get the unique identifier from the overlay information. + * + *

The return value of this function can be used to unregister the related overlay. + * + * @return an identifier representing the current overlay. + * @see OverlayManagerTransaction.Builder#unregisterFabricatedOverlay(OverlayIdentifier) * @hide */ @Override @@ -415,7 +437,7 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { } @Override - public void writeToParcel(Parcel dest, int flags) { + public void writeToParcel(@NonNull Parcel dest, int flags) { dest.writeString(packageName); dest.writeString(overlayName); dest.writeString(targetPackageName); @@ -429,7 +451,7 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { dest.writeBoolean(isFabricated); } - public static final @android.annotation.NonNull Parcelable.Creator CREATOR = + public static final @NonNull Parcelable.Creator CREATOR = new Parcelable.Creator() { @Override public OverlayInfo createFromParcel(Parcel source) { @@ -492,6 +514,11 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { } } + /** + * {@inheritDoc} + * + * @hide + */ @Override public int hashCode() { final int prime = 31; @@ -508,6 +535,11 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { return result; } + /** + * {@inheritDoc} + * + * @hide + */ @Override public boolean equals(@Nullable Object obj) { if (this == obj) { @@ -547,6 +579,11 @@ public final class OverlayInfo implements CriticalOverlayInfo, Parcelable { return true; } + /** + * {@inheritDoc} + * + * @hide + */ @NonNull @Override public String toString() { -- cgit v1.2.3-59-g8ed1b