1 /*
2  * Copyright (C) 2024 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 
17 package android.annotation;
18 
19 
20 import static java.lang.annotation.ElementType.TYPE;
21 
22 import java.lang.annotation.Repeatable;
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 import java.lang.annotation.Target;
26 
27 /**
28  * Indicates if an API is restricted in certain environments.
29  *
30  * <p>
31  * The explicit annotation aids in surfacing the restriction to the developers of the environments
32  * in multiple ways:
33  * </p>
34  *
35  * <ul>
36  * <li>Metalava will consume these annotations to generate appropriate javadocs.</li>
37  * <li>Linters will consume these annotation to show warning to developers on their IDE.</li>
38  * <li>Tests will consume these annotation to verify restricted APIs have been annotated.</li>
39  * </ul>
40  *
41  * @hide
42  */
43 @Target({TYPE})
44 @Retention(RetentionPolicy.RUNTIME)
45 @Repeatable(RestrictedFor.Container.class)
46 public @interface RestrictedFor {
47 
48     /** List of environments where the entity is restricted. */
environments()49     Environment[] environments();
50 
51     /**
52      * SDK version since when the restriction started.
53      *
54      * Possible values are defined in {@link android.os.Build.VERSION_CODES}.
55      */
from()56     int from();
57 
58     enum Environment {
59         /**
60          * See {@link android.app.sdksandbox.SdkSandboxManager}
61          */
62         SDK_SANDBOX {
63             @Override
toString()64             public String toString() {
65                 return "SDK Runtime";
66             }
67         }
68     }
69 
70     /**
71      * Container for {@link RestrictedFor} that allows it to be applied repeatedly to types.
72      */
73     @Retention(RetentionPolicy.RUNTIME)
74     @Target(TYPE)
75     @interface Container {
value()76         RestrictedFor[] value();
77     }
78 }
79