1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.annotation;
import static java.lang.annotation.ElementType.CONSTRUCTOR;
import static java.lang.annotation.ElementType.FIELD;
import static java.lang.annotation.ElementType.METHOD;
import static java.lang.annotation.ElementType.TYPE;
import static java.lang.annotation.RetentionPolicy.CLASS;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.Target;
/**
* Indicates that this non-SDK interface is used by apps. A non-SDK interface is a
* class member (field or method) that is not part of the public SDK. Since the
* member is not part of the SDK, usage by apps is not supported.
*
* <h2>If you are an Android App developer</h2>
*
* This annotation indicates that you may be able to access the member, but that
* this access is discouraged and not supported by Android. If there is a value
* for {@link #maxTargetSdk()} on the annotation, access will be restricted based
* on the {@code targetSdkVersion} value set in your manifest.
*
* <p>Fields and methods annotated with this are likely to be restricted, changed
* or removed in future Android releases. If you rely on these members for
* functionality that is not otherwise supported by Android, consider filing a
* <a href="http://g.co/dev/appcompat">feature request</a>.
*
* <h2>If you are an Android OS developer</h2>
*
* This annotation acts as a heads up that changing a given method or field
* may affect apps, potentially breaking them when the next Android version is
* released. In some cases, for members that are heavily used, this annotation
* may imply restrictions on changes to the member.
*
* <p>This annotation also results in access to the member being permitted by the
* runtime, with a warning being generated in debug builds. Which apps can access
* the member is determined by the value of {@link #maxTargetSdk()}.
*
* <p>For more details, see go/UnsupportedAppUsage.
*
* {@hide}
*/
@Retention(CLASS)
@Target({CONSTRUCTOR, METHOD, FIELD, TYPE})
@Repeatable(UnsupportedAppUsage.Container.class)
public @interface UnsupportedAppUsage {
/**
* Associates a bug tracking the work to add a public alternative to this API. Optional.
*
* @return ID of the associated tracking bug
*/
long trackingBug() default 0;
/**
* Indicates that usage of this API is limited to apps based on their target SDK version.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* @return A dex API signature.
*/
String expectedSignature() default "";
/**
* The signature of an implicit (not present in the source) member that forms part of the
* hiddenapi.
*
* <p>Allows access to non-SDK API elements that are not represented in the input source to be
* managed.
*
* <p>This must only be used when applying the annotation to a type, using it in any other
* situation is an error.
*
* @return A dex API signature.
*/
String implicitMember() default "";
/**
* Public API alternatives to this API.
*
* <p>If non-empty, the string must be a description of the public API alternative(s) to this
* API. The explanation must contain at least one Javadoc link tag to public API methods or
* fields. e.g.:
* {@literal @UnsupportedAppUsage(publicAlternatives="Use {@link foo.bar.Baz#bat()} instead.")}
*
* <p>Any elements that can be deduced can be omitted, e.g.:
* <ul>
* <li>
* the class, if it's the same as for the annotated element.
* </li>
* <li>
* the package name, if it's the same as for the annotated element.
* </li>
* <li>
* the method parameters, if there is only one method with that name in the given
* package and class.
* </li>
* </ul>
* @return A Javadoc-formatted string.
*/
@SuppressWarnings("JavadocReference")
String publicAlternatives() default "";
/**
* Container for {@link UnsupportedAppUsage} that allows it to be applied repeatedly to types.
*/
@Retention(CLASS)
@Target(TYPE)
@interface Container {
UnsupportedAppUsage[] value();
}
}
|
