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
diff --git a/core/api/system-current.txt b/core/api/system-current.txt
index 9e2f54f..fd28f97 100644
--- a/core/api/system-current.txt
+++ b/core/api/system-current.txt
@@ -3427,7 +3427,7 @@
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<android.content.om.OverlayInfo> CREATOR;
}
diff --git a/core/java/android/content/om/OverlayIdentifier.java b/core/java/android/content/om/OverlayIdentifier.java
index 454d0d1..a43091e 100644
--- a/core/java/android/content/om/OverlayIdentifier.java
+++ b/core/java/android/content/om/OverlayIdentifier.java
@@ -27,32 +27,44 @@
/**
* A key used to uniquely identify a Runtime Resource Overlay (RRO).
+ * <!-- For applications -->
*
- * 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
+ * <p>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.
+ *
+ * <!-- For OverlayManagerService, it isn't public part and hidden by HTML comment. -->
+ * <!--
+ * <p>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.
+ * -->
+ *
+ * @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 @@
* 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 @@
- // 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 @@
/**
* Retrieves the package name containing or owning the overlay.
+ *
+ * @hide
*/
@DataClass.Generated.Member
public @Nullable String getPackageName() {
@@ -109,12 +129,18 @@
/**
* 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 @@
&& Objects.equals(mOverlayName, that.mOverlayName);
}
+ /**
+ * {@inheritDoc}
+ * @hide
+ */
@Override
@DataClass.Generated.Member
public int hashCode() {
@@ -144,6 +174,10 @@
return _hash;
}
+ /**
+ * {@inheritDoc}
+ * @hide
+ */
@Override
@DataClass.Generated.Member
public void writeToParcel(@NonNull Parcel dest, int flags) {
@@ -158,6 +192,10 @@
if (mOverlayName != null) dest.writeString(mOverlayName);
}
+ /**
+ * {@inheritDoc}
+ * @hide
+ */
@Override
@DataClass.Generated.Member
public int describeContents() { return 0; }
@@ -165,7 +203,7 @@
/** @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 @@
};
@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 a470de2..a81d16ab 100644
--- a/core/java/android/content/om/OverlayInfo.java
+++ b/core/java/android/content/om/OverlayInfo.java
@@ -33,9 +33,19 @@
import java.util.Objects;
/**
+ * An immutable information about an overlay.
+ *
+ * <p>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.
+ *
+ * <!-- For OverlayManagerService, it isn't public part and hidden by HTML comment. -->
+ * <!--
* Immutable overlay information about a package. All PackageInfos that
* represent an overlay package will have a corresponding OverlayInfo.
+ * -->
*
+ * @see OverlayManager#getOverlayInfosForTarget(String)
* @hide
*/
@SystemApi
@@ -174,14 +184,14 @@
*
* @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 @@
}
/** @hide */
- public OverlayInfo(Parcel source) {
+ public OverlayInfo(@NonNull Parcel source) {
packageName = source.readString();
overlayName = source.readString();
targetPackageName = source.readString();
@@ -299,7 +309,9 @@
}
/**
- * {@inheritDoc}
+ * Get the overlay name from the registered fabricated overlay.
+ *
+ * @return the overlay name
* @hide
*/
@Override
@@ -309,7 +321,9 @@
}
/**
- * {@inheritDoc}
+ * Returns the name of the target overlaid package.
+ *
+ * @return the target package name
* @hide
*/
@Override
@@ -342,11 +356,13 @@
}
/**
- * {@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 @@
*
* @hide
*/
+ @NonNull
public String getBaseCodePath() {
return baseCodePath;
}
/**
- * {@inheritDoc}
+ * Get the unique identifier from the overlay information.
+ *
+ * <p>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 @@
}
@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 @@
dest.writeBoolean(isFabricated);
}
- public static final @android.annotation.NonNull Parcelable.Creator<OverlayInfo> CREATOR =
+ public static final @NonNull Parcelable.Creator<OverlayInfo> CREATOR =
new Parcelable.Creator<OverlayInfo>() {
@Override
public OverlayInfo createFromParcel(Parcel source) {
@@ -492,6 +514,11 @@
}
}
+ /**
+ * {@inheritDoc}
+ *
+ * @hide
+ */
@Override
public int hashCode() {
final int prime = 31;
@@ -508,6 +535,11 @@
return result;
}
+ /**
+ * {@inheritDoc}
+ *
+ * @hide
+ */
@Override
public boolean equals(@Nullable Object obj) {
if (this == obj) {
@@ -547,6 +579,11 @@
return true;
}
+ /**
+ * {@inheritDoc}
+ *
+ * @hide
+ */
@NonNull
@Override
public String toString() {