Add @CovariantReturnType annotation to @CorePlatformApi.

The annotation tells the build toolchain to generate a synthetic
method overload that returns a different type, which is useful
to evolve an API to change its return type to become a more
specific sub-type. Note that a CTS test is needed to verify that
each expected overload is present at runtime.

Also, note that this CL also adds the nested annotation
@CovariantReturnTypes and its values() function to the
@CorePlatformApi because it is required by @Repeated.

For an existing example, see http://r.android.com/884453 (commit
d708f23a17ac382fde8ddda029430cf88821621f).

Test: Treehugger
Fixes: 139739718

Change-Id: I056074b0c3e741696636182ce70ebbe088aefc9e

2 files changed, 19 insertions, 0 deletions

diff --git a/dalvik/src/main/java/dalvik/annotation/codegen/CovariantReturnType.java b/dalvik/src/main/java/dalvik/annotation/codegen/CovariantReturnType.java
index f3028506ac..b43600d93a 100644
--- a/dalvik/src/main/java/dalvik/annotation/codegen/CovariantReturnType.java
+++ b/dalvik/src/main/java/dalvik/annotation/codegen/CovariantReturnType.java
@@ -21,6 +21,7 @@ import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import libcore.api.CorePlatformApi;
 
 /**
  * Indicates to the platform toolchain that there is an upcoming public SDK API change for a method.
@@ -60,24 +61,29 @@ import java.lang.annotation.Target;
 @Repeatable(CovariantReturnType.CovariantReturnTypes.class)
 @Retention(RetentionPolicy.CLASS)
 @Target({ ElementType.METHOD})
+@CorePlatformApi
 public @interface CovariantReturnType {
 
     /**
      * The return type of the synthetic method to generate. Must be a subclass of the return type
      * of the method being annotated.
      */
+    @CorePlatformApi
     Class<?> returnType();
 
     /**
      * The last Android API level not to have the generated synthetic method. The annotation can be
      * removed and the actual return type updated when support for this API level is dropped.
      */
+    @CorePlatformApi
     int presentAfter();
 
     /** @hide */
     @Retention(RetentionPolicy.CLASS)
     @Target({ElementType.METHOD})
+    @CorePlatformApi
     @interface CovariantReturnTypes {
+        @CorePlatformApi
         CovariantReturnType[] value();
     }
 }
diff --git a/mmodules/core_platform_api/api/platform/current-api.txt b/mmodules/core_platform_api/api/platform/current-api.txt
index 1810c8adeb..575797272e 100644
--- a/mmodules/core_platform_api/api/platform/current-api.txt
+++ b/mmodules/core_platform_api/api/platform/current-api.txt
@@ -633,6 +633,19 @@ package com.android.org.conscrypt {
 
 }
 
+package dalvik.annotation.codegen {
+
+  @java.lang.annotation.Repeatable(CovariantReturnType.CovariantReturnTypes.class) @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.CLASS) @java.lang.annotation.Target({java.lang.annotation.ElementType.METHOD}) public @interface CovariantReturnType {
+    method public abstract int presentAfter();
+    method public abstract Class<?> returnType();
+  }
+
+  @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.CLASS) @java.lang.annotation.Target({java.lang.annotation.ElementType.METHOD}) public static @interface CovariantReturnType.CovariantReturnTypes {
+    method public abstract dalvik.annotation.codegen.CovariantReturnType[] value();
+  }
+
+}
+
 package dalvik.annotation.compat {
 
   @java.lang.annotation.Repeatable(UnsupportedAppUsage.Container.class) @java.lang.annotation.Retention(java.lang.annotation.RetentionPolicy.CLASS) @java.lang.annotation.Target({java.lang.annotation.ElementType.CONSTRUCTOR, java.lang.annotation.ElementType.METHOD, java.lang.annotation.ElementType.FIELD, java.lang.annotation.ElementType.TYPE}) public @interface UnsupportedAppUsage {