Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Prepare comments and annotations for OverlayInfo & OverlayIdentifier public API

Browse Source 
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
This commit is contained in:
felkachang
2022-12-07 08:00:29 +00:00
parent ccc347f14a
commit eaa0ad10e8
3 changed files with 99 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
core/api/system-current.txt
View File

@@ -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<android.content.om.OverlayInfo> CREATOR;
}

64
core/java/android/content/om/OverlayIdentifier.java
View File

@@ -27,32 +27,44 @@ import java.util.Objects;
/**
* 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 @@ 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() {}

57
core/java/android/content/om/OverlayInfo.java
View File

@@ -33,9 +33,19 @@ import java.lang.annotation.RetentionPolicy;
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 @@ 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.
*
* <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 @@ 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<OverlayInfo> CREATOR =
public static final @NonNull Parcelable.Creator<OverlayInfo> CREATOR =
new Parcelable.Creator<OverlayInfo>() {
@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() {