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;
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, 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      *         {@link android.os.Build.VERSION_CODES#O} or {@link android.os.Build.VERSION_CODES#P},
87      *         to limit access to apps targeting these SDKs (or earlier).
88      *     </li>
89      *     <li>
90      *         absent (default value) - All apps can access this API, but doing so may result in
91      *         warnings in the log, UI warnings (on developer builds) and/or strictmode violations.
92      *         The API is likely to be further restricted in future.
93      *     </li>
94      *
95      * </ul>
96      *
97      * Note, if this is set to {@link android.os.Build.VERSION_CODES#O}, apps targeting O
98      * maintenance releases will also be allowed to use the API, and similarly for any future
99      * maintenance releases of P.
100      *
101      * @return The maximum value for an apps targetSdkVersion in order to access this API.
102      */
maxTargetSdk()103     int maxTargetSdk() default Integer.MAX_VALUE;
104 
105     /**
106      * For debug use only. The expected dex signature to be generated for this API, used to verify
107      * parts of the build process.
108      *
109      * @return A dex API signature.
110      */
expectedSignature()111     String expectedSignature() default "";
112 
113     /**
114      * The signature of an implicit (not present in the source) member that forms part of the
115      * hiddenapi.
116      *
117      * <p>Allows access to non-SDK API elements that are not represented in the input source to be
118      * managed.
119      *
120      * <p>This must only be used when applying the annotation to a type, using it in any other
121      * situation is an error.
122      *
123      * @return A dex API signature.
124      */
implicitMember()125     String implicitMember() default "";
126 
127     /**
128      * Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types.
129      */
130     @Retention(CLASS)
131     @Target(TYPE)
132     @interface Container {
value()133         UnsupportedAppUsage[] value();
134     }
135 }
136