From 5ffffa570223cbd745ba365c5c837853d472f373 Mon Sep 17 00:00:00 2001
From: Hani Kazmi <hanikazmi@google.com>
Date: Mon, 1 Aug 2022 16:26:49 +0000
Subject: Add javadoc note about bug in readParcelableCreatorInternal

follow up to b/232589966. Bug was fixed in master, but did not have time
to merge into T. Adding a note to aid developers in using the old API if
impacted.

Test: m
Bug: 240585930
Change-Id: Ibd80007b63ff8d2ad87e18c6c4d0ffedb5184ff5
---
 core/java/android/os/Bundle.java | 27 ++++++++++++++++++++
 core/java/android/os/Parcel.java | 53 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/core/java/android/os/Bundle.java b/core/java/android/os/Bundle.java
index 7e355d95cdb3..e845ffa2c43c 100644
--- a/core/java/android/os/Bundle.java
+++ b/core/java/android/os/Bundle.java
@@ -934,6 +934,12 @@ public final class Bundle extends BaseBundle implements Cloneable, Parcelable {
      * you must call {@link #setClassLoader(ClassLoader)} with the proper {@link ClassLoader} first.
      * Otherwise, this method might throw an exception or return {@code null}.
      *
+     * <p><b>Warning: </b> the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #getParcelable(String)} instead.
+     *
      * @param key a String, or {@code null}
      * @param clazz The type of the object expected
      * @return a Parcelable value, or {@code null}
@@ -990,6 +996,13 @@ public final class Bundle extends BaseBundle implements Cloneable, Parcelable {
      * you must call {@link #setClassLoader(ClassLoader)} with the proper {@link ClassLoader} first.
      * Otherwise, this method might throw an exception or return {@code null}.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #getParcelableArray(String)} instead.
+     *
      * @param key a String, or {@code null}
      * @param clazz The type of the items inside the array. This is only verified when unparceling.
      * @return a Parcelable[] value, or {@code null}
@@ -1054,6 +1067,13 @@ public final class Bundle extends BaseBundle implements Cloneable, Parcelable {
      * you must call {@link #setClassLoader(ClassLoader)} with the proper {@link ClassLoader} first.
      * Otherwise, this method might throw an exception or return {@code null}.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #getParcelableArrayList(String)} instead.
+     *
      * @param key   a String, or {@code null}
      * @param clazz The type of the items inside the array list. This is only verified when
      *     unparceling.
@@ -1105,6 +1125,13 @@ public final class Bundle extends BaseBundle implements Cloneable, Parcelable {
      *     <li>The object is not of type {@code clazz}.
      * </ul>
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #getSparseParcelableArray(String)} instead.
+     *
      * @param key a String, or null
      * @param clazz The type of the items inside the sparse array. This is only verified when
      *     unparceling.
diff --git a/core/java/android/os/Parcel.java b/core/java/android/os/Parcel.java
index 2664f05a9664..3d701389a98e 100644
--- a/core/java/android/os/Parcel.java
+++ b/core/java/android/os/Parcel.java
@@ -3235,6 +3235,13 @@ public final class Parcel {
      * Same as {@link #readList(List, ClassLoader)} but accepts {@code clazz} parameter as
      * the type required for each item.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readList(List, ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
@@ -3463,6 +3470,13 @@ public final class Parcel {
      * Same as {@link #readArrayList(ClassLoader)} but accepts {@code clazz} parameter as
      * the type required for each item.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readArrayList(ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
@@ -3497,6 +3511,13 @@ public final class Parcel {
      * Same as {@link #readArray(ClassLoader)} but accepts {@code clazz} parameter as
      * the type required for each item.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readArray(ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
@@ -3530,6 +3551,13 @@ public final class Parcel {
      * Same as {@link #readSparseArray(ClassLoader)} but accepts {@code clazz} parameter as
      * the type required for each item.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readSparseArray(ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
@@ -3847,6 +3875,13 @@ public final class Parcel {
      * Same as {@link #readParcelableList(List, ClassLoader)} but accepts {@code clazz} parameter as
      * the type required for each item.
      *
+     * <p><b>Warning: </b> if the list contains items implementing the {@link Parcelable} interface,
+     * the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readParcelableList(List, ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
@@ -4744,6 +4779,12 @@ public final class Parcel {
      * Same as {@link #readParcelable(ClassLoader)} but accepts {@code clazz} parameter as the type
      * required for each item.
      *
+     * <p><b>Warning: </b> the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readParcelable(ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
@@ -4812,6 +4853,12 @@ public final class Parcel {
      * Same as {@link #readParcelableCreator(ClassLoader)} but accepts {@code clazz} parameter
      * as the required type.
      *
+     * <p><b>Warning: </b> the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readParcelableCreator(ClassLoader) instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there there was an error
      * trying to read the {@link Parcelable.Creator}.
@@ -4939,6 +4986,12 @@ public final class Parcel {
      * Same as {@link #readParcelableArray(ClassLoader)}  but accepts {@code clazz} parameter as
      * the type required for each item.
      *
+     * <p><b>Warning: </b> the class that implements {@link Parcelable} has to be the immediately
+     * enclosing class of the runtime type of its CREATOR field (that is,
+     * {@link Class#getEnclosingClass()} has to return the parcelable implementing class),
+     * otherwise this method might throw an exception. If the Parcelable class does not enclose the
+     * CREATOR, use the deprecated {@link #readParcelableArray(ClassLoader)} instead.
+     *
      * @throws BadParcelableException Throws BadParcelableException if the item to be deserialized
      * is not an instance of that class or any of its children classes or there was an error
      * trying to instantiate an element.
-- 
cgit v1.2.3-59-g8ed1b