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 dalvik.annotation.compat; 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 dalvik.system.VersionCodes; 25 import java.lang.annotation.Repeatable; 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.Target; 28 import libcore.api.CorePlatformApi; 29 import libcore.api.IntraCoreApi; 30 31 /** 32 * Indicates that a class member, that is not part of the SDK, is used by apps. 33 * Since the member is not part of the SDK, such use is not supported. 34 * 35 * <p>This annotation acts as a heads up that changing a given method or field 36 * may affect apps, potentially breaking them when the next Android version is 37 * released. In some cases, for members that are heavily used, this annotation 38 * may imply restrictions on changes to the member. 39 * 40 * <p>This annotation also results in access to the member being permitted by the 41 * runtime, with a warning being generated in debug builds. 42 * 43 * <p>For more details, see go/UnsupportedAppUsage. 44 * 45 * {@hide} 46 */ 47 @Retention(CLASS) 48 @Target({CONSTRUCTOR, METHOD, FIELD, TYPE}) 49 @Repeatable(UnsupportedAppUsage.Container.class) 50 @CorePlatformApi 51 @IntraCoreApi 52 public @interface UnsupportedAppUsage { 53 54 /** 55 * Associates a bug tracking the work to add a public alternative to this API. Optional. 56 * 57 * @return ID of the associated tracking bug 58 */ 59 @CorePlatformApi 60 @IntraCoreApi trackingBug()61 long trackingBug() default 0; 62 63 /** 64 * Indicates that usage of this API is limited to apps based on their target SDK version. 65 * 66 * <p>Access to the API is allowed if the targetSdkVersion in the apps manifest is no greater 67 * than this value. Access checks are performed at runtime. 68 * 69 * <p>This is used to give app developers a grace period to migrate off a non-SDK interface. 70 * When making Android version N, existing APIs can have a maxTargetSdk of N-1 added to them. 71 * Developers must then migrate off the API when their app is updated in future, but it will 72 * continue working in the meantime. 73 * 74 * <p>Possible values are: 75 * <ul> 76 * <li> 77 * {@link VersionCodes#O} - in which case the API is available up to and including the 78 * O release and all intermediate releases between O and P. Or in other words the API 79 * is blacklisted (unavailable) from P onwards. 80 * </li> 81 * <li> 82 * {@link VersionCodes#P} - in which case the API is available up to and including the 83 * P release and all intermediate releases between P and Q. Or in other words the API 84 * is blacklisted (unavailable) from Q onwards. 85 * </li> 86 * <li> 87 * absent (default value) - All apps can access this API, but doing so may result in 88 * warnings in the log, UI warnings (on developer builds) and/or strictmode violations. 89 * The API is likely to be further restricted in future. 90 * </li> 91 * 92 * </ul> 93 * 94 * @return The maximum value for an apps targetSdkVersion in order to access this API. 95 */ 96 @CorePlatformApi 97 @IntraCoreApi maxTargetSdk()98 int maxTargetSdk() default Integer.MAX_VALUE; 99 100 /** 101 * For debug use only. The expected dex signature to be generated for this API, used to verify 102 * parts of the build process. 103 * 104 * @return A dex API signature. 105 */ 106 @CorePlatformApi 107 @IntraCoreApi expectedSignature()108 String expectedSignature() default ""; 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 @CorePlatformApi 123 @IntraCoreApi implicitMember()124 String implicitMember() default ""; 125 126 /** 127 * Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types. 128 */ 129 @Retention(CLASS) 130 @Target(TYPE) 131 @CorePlatformApi 132 @IntraCoreApi 133 @interface Container { 134 @CorePlatformApi 135 @IntraCoreApi value()136 UnsupportedAppUsage[] value(); 137 } 138 } 139