Merge "Expose 'ParcelableHolder' as SystemApi" am: 135efb0b73

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/1458065

Change-Id: I1d9dd79cddd79dab7aa077e4be393facfaf5afcb

api/module-lib-current.txt

@@ -47,8 +47,6 @@ package android.os {
 
   public interface Parcelable {
     method public default int getStability();
-    field public static final int PARCELABLE_STABILITY_LOCAL = 0; // 0x0
-    field public static final int PARCELABLE_STABILITY_VINTF = 1; // 0x1
   }
 
   public class StatsFrameworkInitializer {

api/system-current.txt

@@ -8350,6 +8350,22 @@ package android.os {
     method public boolean hasSingleFileDescriptor();
   }
 
+  public interface Parcelable {
+    field public static final int PARCELABLE_STABILITY_LOCAL = 0; // 0x0
+    field public static final int PARCELABLE_STABILITY_VINTF = 1; // 0x1
+  }
+
+  public final class ParcelableHolder implements android.os.Parcelable {
+    ctor public ParcelableHolder(int);
+    method public int describeContents();
+    method @Nullable public <T extends android.os.Parcelable> T getParcelable(@NonNull Class<T>);
+    method public int getStability();
+    method public void readFromParcel(@NonNull android.os.Parcel);
+    method public boolean setParcelable(@Nullable android.os.Parcelable);
+    method public void writeToParcel(@NonNull android.os.Parcel, int);
+    field @NonNull public static final android.os.Parcelable.Creator<android.os.ParcelableHolder> CREATOR;
+  }
+
   public final class PowerManager {
     method @RequiresPermission(allOf={android.Manifest.permission.READ_DREAM_STATE, android.Manifest.permission.WRITE_DREAM_STATE}) public void dream(long);
     method @RequiresPermission(android.Manifest.permission.DEVICE_POWER) public boolean forceSuspend();

core/java/android/os/Parcelable.java

@@ -120,7 +120,7 @@ public interface Parcelable {
      * @see ParcelableHolder
      * @hide
      */
-    @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
+    @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS)
     public static final int PARCELABLE_STABILITY_LOCAL = 0x0000;
     /**
      * Something that is meant to be used between system and vendor.
@@ -128,7 +128,7 @@ public interface Parcelable {
      * @see ParcelableHolder
      * @hide
      */
-    @SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
+    @SystemApi(client = SystemApi.Client.PRIVILEGED_APPS)
     public static final int PARCELABLE_STABILITY_VINTF = 0x0001;
 
     /**

core/java/android/os/ParcelableHolder.java

@@ -18,12 +18,54 @@ package android.os;
 
 import android.annotation.NonNull;
 import android.annotation.Nullable;
+import android.annotation.SystemApi;
 import android.util.MathUtils;
 
 /**
- * Parcelable containing the other Parcelable object.
+ * ParcelableHolder is a Parcelable which can contain another Parcelable.
+ * The main use case of ParcelableHolder is to make a Parcelable extensible.
+ * For example, an AOSP-defined Parcelable <code>AospDefinedParcelable</code>
+ * is expected to be extended by device implementers for their value-add features.
+ * Previously without ParcelableHolder, the device implementers had to
+ * directly modify the Parcelable to add more fields:
+ * <pre> {@code
+ * parcelable AospDefinedParcelable {
+ *   int a;
+ *   String b;
+ *   String x; // added by a device implementer
+ *   int[] y; // added by a device implementer
+ * }}</pre>
+ *
+ * This practice is very error-prone because the fields added by the device implementer
+ * might have a conflict when the Parcelable is revisioned in the next releases of Android.
+ *
+ * Using ParcelableHolder, one can define an extension point in a Parcelable.
+ * <pre> {@code
+ * parcelable AospDefinedParcelable {
+ *   int a;
+ *   String b;
+ *   ParcelableHolder extension;
+ * }}</pre>
+ * Then the device implementers can define their own Parcelable for their extension.
+ *
+ * <pre> {@code
+ * parcelable OemDefinedParcelable {
+ *   String x;
+ *   int[] y;
+ * }}</pre>
+ * Finally, the new Parcelable can be attached to the original Parcelable via
+ * the ParcelableHolder field.
+ *
+ * <pre> {@code
+ * AospDefinedParcelable ap = ...;
+ * OemDefinedParcelable op = new OemDefinedParcelable();
+ * op.x = ...;
+ * op.y = ...;
+ * ap.extension.setParcelable(op);}</pre>
+ *
  * @hide
  */
+@SystemApi
 public final class ParcelableHolder implements Parcelable {
     /**
      * This is set by {@link #setParcelable}.
@@ -80,7 +122,7 @@ public final class ParcelableHolder implements Parcelable {
      * Write a parcelable into ParcelableHolder, the previous parcelable will be removed.
      * @return {@code false} if the parcelable's stability is more unstable ParcelableHolder.
      */
-    public synchronized boolean setParcelable(@Nullable Parcelable p) {
+    public boolean setParcelable(@Nullable Parcelable p) {
         // a ParcelableHolder can only hold things at its stability or higher
         if (p != null && this.getStability() > p.getStability()) {
             return false;
@@ -99,7 +141,7 @@ public final class ParcelableHolder implements Parcelable {
      *         the type written by (@link #setParcelable}.
      */
     @Nullable
-    public synchronized <T extends Parcelable> T getParcelable(@NonNull Class<T> clazz) {
+    public <T extends Parcelable> T getParcelable(@NonNull Class<T> clazz) {
         if (mParcel == null) {
             if (!clazz.isInstance(mParcelable)) {
                 return null;
@@ -123,7 +165,7 @@ public final class ParcelableHolder implements Parcelable {
     /**
      * Read ParcelableHolder from a parcel.
      */
-    public synchronized void readFromParcel(@NonNull Parcel parcel) {
+    public void readFromParcel(@NonNull Parcel parcel) {
         this.mStability = parcel.readInt();
 
         mParcelable = null;
@@ -145,7 +187,7 @@ public final class ParcelableHolder implements Parcelable {
     }
 
     @Override
-    public synchronized void writeToParcel(@NonNull Parcel parcel, int flags) {
+    public void writeToParcel(@NonNull Parcel parcel, int flags) {
         parcel.writeInt(this.mStability);
 
         if (mParcel != null) {
@@ -166,7 +208,7 @@ public final class ParcelableHolder implements Parcelable {
     }
 
     @Override
-    public synchronized int describeContents() {
+    public int describeContents() {
         if (mParcel != null) {
             return mParcel.hasFileDescriptors() ? Parcelable.CONTENTS_FILE_DESCRIPTOR : 0;
         }

non-updatable-api/module-lib-current.txt

@@ -7,8 +7,6 @@ package android.os {
 
   public interface Parcelable {
     method public default int getStability();
-    field public static final int PARCELABLE_STABILITY_LOCAL = 0; // 0x0
-    field public static final int PARCELABLE_STABILITY_VINTF = 1; // 0x1
   }
 
   public class StatsServiceManager {

non-updatable-api/system-current.txt

@@ -7270,6 +7270,22 @@ package android.os {
     method public boolean hasSingleFileDescriptor();
   }
 
+  public interface Parcelable {
+    field public static final int PARCELABLE_STABILITY_LOCAL = 0; // 0x0
+    field public static final int PARCELABLE_STABILITY_VINTF = 1; // 0x1
+  }
+
+  public final class ParcelableHolder implements android.os.Parcelable {
+    ctor public ParcelableHolder(int);
+    method public int describeContents();
+    method @Nullable public <T extends android.os.Parcelable> T getParcelable(@NonNull Class<T>);
+    method public int getStability();
+    method public void readFromParcel(@NonNull android.os.Parcel);
+    method public boolean setParcelable(@Nullable android.os.Parcelable);
+    method public void writeToParcel(@NonNull android.os.Parcel, int);
+    field @NonNull public static final android.os.Parcelable.Creator<android.os.ParcelableHolder> CREATOR;
+  }
+
   public final class PowerManager {
     method @RequiresPermission(allOf={android.Manifest.permission.READ_DREAM_STATE, android.Manifest.permission.WRITE_DREAM_STATE}) public void dream(long);
     method @RequiresPermission(android.Manifest.permission.DEVICE_POWER) public boolean forceSuspend();