1 /* 2 * Copyright (C) 2019 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.compat.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; 21 import static java.lang.annotation.ElementType.TYPE; 22 import static java.lang.annotation.RetentionPolicy.CLASS; 23 24 import java.lang.annotation.Repeatable; 25 import java.lang.annotation.Retention; 26 import java.lang.annotation.Target; 27 28 /** 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. 32 * 33 * <h2>If you are an Android App developer</h2> 34 * 35 * This annotation indicates that you may be able to access the member at runtime, 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 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 * 52 * <p>This annotation also results in access to the member being permitted by the 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()}. 55 * 56 * <p>For more details, see go/UnsupportedAppUsage. 57 * 58 * {@hide} 59 */ 60 @Retention(CLASS) 61 @Target({CONSTRUCTOR, METHOD, FIELD, TYPE}) 62 @Repeatable(UnsupportedAppUsage.Container.class) 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 */ trackingBug()70 long trackingBug() default 0; 71 72 /** 73 * Indicates that usage of this API is limited to apps based on their target SDK version. 74 * 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. 77 * 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. 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 * 83 * <p>Possible values are: 84 * <ul> 85 * <li> 86 * An API level like {@link VersionCodes#O} - in which case the API is available up to 87 * and including the specified release. Or, in other words, access to the API is 88 * blocked (unavailable) from the next API level from the one specified. 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 * 98 * @return The maximum value for an apps targetSdkVersion in order to access this API. 99 */ maxTargetSdk()100 int maxTargetSdk() default Integer.MAX_VALUE; 101 102 /** 103 * The signature of an implicit (not present in the source) member that forms part of the 104 * hiddenapi. 105 * 106 * <p>Allows access to non-SDK API elements that are not represented in the input source to be 107 * managed. 108 * 109 * <p>This must only be used when applying the annotation to a type, using it in any other 110 * situation is an error. 111 * 112 * @return A dex API signature. 113 */ implicitMember()114 String implicitMember() default ""; 115 116 /** 117 * Public API alternatives to this API. 118 * 119 * <p>If non-empty, the string must be a description of the public API alternative(s) to this 120 * API. The explanation must contain at least one Javadoc link tag to public API methods or 121 * fields. e.g.: 122 * {@literal @UnsupportedAppUsage(publicAlternatives="Use {@link foo.bar.Baz#bat()} instead.")} 123 * 124 * <p>Any elements that can be deduced can be omitted, e.g.: 125 * <ul> 126 * <li> 127 * the class, if it's the same as for the annotated element. 128 * </li> 129 * <li> 130 * the package name, if it's the same as for the annotated element. 131 * </li> 132 * <li> 133 * the method parameters, if there is only one method with that name in the given 134 * package and class. 135 * </li> 136 * </ul> 137 * @return A Javadoc-formatted string. 138 */ 139 @SuppressWarnings("JavadocReference") publicAlternatives()140 String publicAlternatives() default ""; 141 142 /** 143 * Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types. 144 */ 145 @Retention(CLASS) 146 @Target(TYPE) 147 @interface Container { value()148 UnsupportedAppUsage[] value(); 149 } 150 151 /** 152 * Internal usage only. 153 * 154 * Override the default source position when generating an index of the annotations. 155 * 156 * <p>This is intended for use by tools that generate java source code, to point to the 157 * original source position of the annotation, rather than the position within the generated 158 * code. It should never be set manually. 159 * 160 * <p>The format of the value is "path/to/file:startline:startcol:endline:endcol" indicating 161 * the position of the annotation itself. 162 */ overrideSourcePosition()163 String overrideSourcePosition() default ""; 164 165 /** 166 * Internal usage only. 167 * 168 * For debug use only. The expected dex signature to be generated for this API, used to verify 169 * parts of the build process. 170 * 171 * @return A dex API signature. 172 */ expectedSignature()173 String expectedSignature() default ""; 174 } 175