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

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

Change-Id: I7af96574a930efed7c5c7d45a0c5bfd40a569d22

2 files changed, 50 insertions, 8 deletions

diff --git a/core/java/android/os/Parcelable.java b/core/java/android/os/Parcelable.java
index f14f66b07630..7a624e1da26c 100644
--- a/core/java/android/os/Parcelable.java
+++ b/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;
 
     /**
diff --git a/core/java/android/os/ParcelableHolder.java b/core/java/android/os/ParcelableHolder.java
index 181f94b39841..95c07b6b2451 100644
--- a/core/java/android/os/ParcelableHolder.java
+++ b/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;
         }