Add maxTargetSdk to @UnsupportedAppUsage annotation.

This will be used by the runtime to limit access to APIs based on their
targetSdkVersion in the manifest.

When adding new maxTargetSdk values to non-SDK interfaces, we use the
SDK version of the latest major (i.e. new letter) release of Android
that has been made public. e.g. while Q is in development, we add new
maxTargetSdk values of 28 (Build.VERSION_CODES.P), even if a P MR1 has
already been released.

We do this because:
- It reduces the number of distinct SDK levels that have to be
  considered and enforced in the runtime.
- Using past releases means that there is always a well established
  value to use.

See go/hidden-api-annotations for more context.

Test: m
Bug: 110868826
Change-Id: Idbe78510acf538ce941a9a61a64fcc0bdc4de38e

1 files changed, 33 insertions, 0 deletions

diff --git a/core/java/android/annotation/UnsupportedAppUsage.java b/core/java/android/annotation/UnsupportedAppUsage.java
index 05de3e8caa3f..fbba6dafde29 100644
--- a/core/java/android/annotation/UnsupportedAppUsage.java
+++ b/core/java/android/annotation/UnsupportedAppUsage.java
@@ -51,6 +51,39 @@ public @interface UnsupportedAppUsage {
     long trackingBug() default 0;
 
     /**
+     * Indicates that usage of this API is limited to apps based on their target SDK version.
+     *
+     * Access to the API is allowed if the targetSdkVersion in the apps manifest is no greater than
+     * this value. Access checks are performed at runtime.
+     *
+     * This is used to give app developers a grace period to migrate off a non-SDK interface. When
+     * making Android version N, existing APIs can have a maxTargetSdk of N-1 added to them.
+     * Developers must then migrate off the API when their app is updated in future, but it will
+     * continue working in the meantime.
+     *
+     * Possible values are:
+     * <ul>
+     *     <li>
+     *         {@link android.os.Build.VERSION_CODES#O} or {@link android.os.Build.VERSION_CODES#P},
+     *         to limit access to apps targeting these SDKs (or earlier).
+     *     </li>
+     *     <li>
+     *         absent (default value) - All apps can access this API, but doing so may result in
+     *         warnings in the log, UI warnings (on developer builds) and/or strictmode violations.
+     *         The API is likely to be further restricted in future.
+     *     </li>
+     *
+     * </ul>
+     *
+     * Note, if this is set to {@link android.os.Build.VERSION_CODES#O}, apps targeting O
+     * maintenance releases will also be allowed to use the API, and similarly for any future
+     * maintenance releases of P.
+     *
+     * @return The maximum value for an apps targetSdkVersion in order to access this API.
+     */
+    int maxTargetSdk() default Integer.MAX_VALUE;
+
+    /**
      * For debug use only. The expected dex signature to be generated for this API, used to verify
      * parts of the build process.
      *