Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2018 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | package android.annotation; |
| 17 | |
| 18 | import static java.lang.annotation.ElementType.CONSTRUCTOR; |
| 19 | import static java.lang.annotation.ElementType.FIELD; |
| 20 | import static java.lang.annotation.ElementType.METHOD; |
Paul Duffin | ed4d7c2 | 2018-12-07 10:40:38 +0000 | [diff] [blame] | 21 | import static java.lang.annotation.ElementType.TYPE; |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 22 | import static java.lang.annotation.RetentionPolicy.CLASS; |
| 23 | |
Paul Duffin | ed4d7c2 | 2018-12-07 10:40:38 +0000 | [diff] [blame] | 24 | import java.lang.annotation.Repeatable; |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 25 | import java.lang.annotation.Retention; |
| 26 | import java.lang.annotation.Target; |
| 27 | |
| 28 | /** |
Mathew Inwood | f653d93 | 2018-12-07 11:15:49 +0000 | [diff] [blame] | 29 | * Indicates that this non-SDK interface is used by apps. A non-SDK interface is a |
| 30 | * class member (field or method) that is not part of the public SDK. Since the |
| 31 | * member is not part of the SDK, usage by apps is not supported. |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 32 | * |
Mathew Inwood | f653d93 | 2018-12-07 11:15:49 +0000 | [diff] [blame] | 33 | * <h2>If you are an Android App developer</h2> |
| 34 | * |
| 35 | * This annotation indicates that you may be able to access the member, but that |
| 36 | * this access is discouraged and not supported by Android. If there is a value |
| 37 | * for {@link #maxTargetSdk()} on the annotation, access will be restricted based |
| 38 | * on the {@code targetSdkVersion} value set in your manifest. |
| 39 | * |
| 40 | * <p>Fields and methods annotated with this are likely to be restricted, changed |
| 41 | * or removed in future Android releases. If you rely on these members for |
| 42 | * functionality that is not otherwise supported by Android, consider filing a |
| 43 | * <a href="http://g.co/dev/appcompat">feature request</a>. |
| 44 | * |
| 45 | * <h2>If you are an Android OS developer</h2> |
| 46 | * |
| 47 | * This annotation acts as a heads up that changing a given method or field |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 48 | * may affect apps, potentially breaking them when the next Android version is |
| 49 | * released. In some cases, for members that are heavily used, this annotation |
| 50 | * may imply restrictions on changes to the member. |
| 51 | * |
Mathew Inwood | 8ea8654 | 2018-08-28 10:52:51 +0100 | [diff] [blame] | 52 | * <p>This annotation also results in access to the member being permitted by the |
Mathew Inwood | f653d93 | 2018-12-07 11:15:49 +0000 | [diff] [blame] | 53 | * runtime, with a warning being generated in debug builds. Which apps can access |
| 54 | * the member is determined by the value of {@link #maxTargetSdk()}. |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 55 | * |
Mathew Inwood | 8ea8654 | 2018-08-28 10:52:51 +0100 | [diff] [blame] | 56 | * <p>For more details, see go/UnsupportedAppUsage. |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 57 | * |
| 58 | * {@hide} |
| 59 | */ |
| 60 | @Retention(CLASS) |
Paul Duffin | ed4d7c2 | 2018-12-07 10:40:38 +0000 | [diff] [blame] | 61 | @Target({CONSTRUCTOR, METHOD, FIELD, TYPE}) |
| 62 | @Repeatable(UnsupportedAppUsage.Container.class) |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 63 | public @interface UnsupportedAppUsage { |
| 64 | |
| 65 | /** |
| 66 | * Associates a bug tracking the work to add a public alternative to this API. Optional. |
| 67 | * |
| 68 | * @return ID of the associated tracking bug |
| 69 | */ |
| 70 | long trackingBug() default 0; |
| 71 | |
| 72 | /** |
Mathew Inwood | d991a40 | 2018-08-16 10:41:36 +0100 | [diff] [blame] | 73 | * Indicates that usage of this API is limited to apps based on their target SDK version. |
| 74 | * |
Mathew Inwood | 8ea8654 | 2018-08-28 10:52:51 +0100 | [diff] [blame] | 75 | * <p>Access to the API is allowed if the targetSdkVersion in the apps manifest is no greater |
| 76 | * than this value. Access checks are performed at runtime. |
Mathew Inwood | d991a40 | 2018-08-16 10:41:36 +0100 | [diff] [blame] | 77 | * |
Mathew Inwood | 8ea8654 | 2018-08-28 10:52:51 +0100 | [diff] [blame] | 78 | * <p>This is used to give app developers a grace period to migrate off a non-SDK interface. |
| 79 | * When making Android version N, existing APIs can have a maxTargetSdk of N-1 added to them. |
Mathew Inwood | d991a40 | 2018-08-16 10:41:36 +0100 | [diff] [blame] | 80 | * Developers must then migrate off the API when their app is updated in future, but it will |
| 81 | * continue working in the meantime. |
| 82 | * |
Mathew Inwood | 8ea8654 | 2018-08-28 10:52:51 +0100 | [diff] [blame] | 83 | * <p>Possible values are: |
Mathew Inwood | d991a40 | 2018-08-16 10:41:36 +0100 | [diff] [blame] | 84 | * <ul> |
| 85 | * <li> |
Neil Fuller | 2422489 | 2019-10-18 17:41:56 +0100 | [diff] [blame] | 86 | * An API level like {@link android.os.Build.VERSION_CODES#O} - in which case the API is |
| 87 | * available up to and including the specified release. Or, in other words, the API is |
| 88 | * blacklisted (unavailable) from the next API level from the one specified. |
Mathew Inwood | d991a40 | 2018-08-16 10:41:36 +0100 | [diff] [blame] | 89 | * </li> |
| 90 | * <li> |
| 91 | * absent (default value) - All apps can access this API, but doing so may result in |
| 92 | * warnings in the log, UI warnings (on developer builds) and/or strictmode violations. |
| 93 | * The API is likely to be further restricted in future. |
| 94 | * </li> |
| 95 | * |
| 96 | * </ul> |
| 97 | * |
Mathew Inwood | d991a40 | 2018-08-16 10:41:36 +0100 | [diff] [blame] | 98 | * @return The maximum value for an apps targetSdkVersion in order to access this API. |
| 99 | */ |
| 100 | int maxTargetSdk() default Integer.MAX_VALUE; |
| 101 | |
| 102 | /** |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 103 | * For debug use only. The expected dex signature to be generated for this API, used to verify |
| 104 | * parts of the build process. |
| 105 | * |
| 106 | * @return A dex API signature. |
| 107 | */ |
| 108 | String expectedSignature() default ""; |
Paul Duffin | ed4d7c2 | 2018-12-07 10:40:38 +0000 | [diff] [blame] | 109 | |
| 110 | /** |
| 111 | * The signature of an implicit (not present in the source) member that forms part of the |
| 112 | * hiddenapi. |
| 113 | * |
| 114 | * <p>Allows access to non-SDK API elements that are not represented in the input source to be |
| 115 | * managed. |
| 116 | * |
| 117 | * <p>This must only be used when applying the annotation to a type, using it in any other |
| 118 | * situation is an error. |
| 119 | * |
| 120 | * @return A dex API signature. |
| 121 | */ |
| 122 | String implicitMember() default ""; |
| 123 | |
| 124 | /** |
Andrei Onea | 7502504 | 2019-04-29 16:45:41 +0100 | [diff] [blame] | 125 | * Public API alternatives to this API. |
| 126 | * |
| 127 | * <p>If non-empty, the string must be a description of the public API alternative(s) to this |
| 128 | * API. The explanation must contain at least one Javadoc link tag to public API methods or |
| 129 | * fields. e.g.: |
| 130 | * {@literal @UnsupportedAppUsage(publicAlternatives="Use {@link foo.bar.Baz#bat()} instead.")} |
| 131 | * |
| 132 | * <p>Any elements that can be deduced can be omitted, e.g.: |
| 133 | * <ul> |
| 134 | * <li> |
| 135 | * the class, if it's the same as for the annotated element. |
| 136 | * </li> |
| 137 | * <li> |
| 138 | * the package name, if it's the same as for the annotated element. |
| 139 | * </li> |
| 140 | * <li> |
| 141 | * the method parameters, if there is only one method with that name in the given |
| 142 | * package and class. |
| 143 | * </li> |
| 144 | * </ul> |
| 145 | * @return A Javadoc-formatted string. |
| 146 | */ |
| 147 | @SuppressWarnings("JavadocReference") |
| 148 | String publicAlternatives() default ""; |
| 149 | |
| 150 | /** |
Mathew Inwood | 2867ddf | 2019-11-29 15:30:52 +0000 | [diff] [blame] | 151 | * Override the default source position when generating an index of the annotations. |
| 152 | * |
| 153 | * <p>This is intended for use by tools that generate java source code, to point to the |
| 154 | * original source position of the annotation, rather than the position within the generated |
| 155 | * code. It should never be set manually. |
| 156 | * |
| 157 | * <p>The format of the value is "path/to/file:startline:startcol:endline:endcol" indicating |
| 158 | * the position of the annotation itself. |
| 159 | */ |
| 160 | String overrideSourcePosition() default ""; |
| 161 | |
| 162 | /** |
Paul Duffin | ed4d7c2 | 2018-12-07 10:40:38 +0000 | [diff] [blame] | 163 | * Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types. |
| 164 | */ |
| 165 | @Retention(CLASS) |
| 166 | @Target(TYPE) |
| 167 | @interface Container { |
| 168 | UnsupportedAppUsage[] value(); |
| 169 | } |
Mathew Inwood | 2e61590 | 2018-06-26 14:06:27 +0100 | [diff] [blame] | 170 | } |