1/*
2 * Copyright (C) 2016 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 */
16package android.support.annotation;
17
18import java.lang.annotation.Retention;
19import java.lang.annotation.Target;
20
21import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
22import static java.lang.annotation.ElementType.CONSTRUCTOR;
23import static java.lang.annotation.ElementType.FIELD;
24import static java.lang.annotation.ElementType.METHOD;
25import static java.lang.annotation.ElementType.PACKAGE;
26import static java.lang.annotation.ElementType.TYPE;
27import static java.lang.annotation.RetentionPolicy.CLASS;
28
29/**
30 * Denotes that the annotated element should only be accessed from within a
31 * specific scope (as defined by {@link Scope}).
32 * <p>
33 * Example of restricting usage within a library (based on gradle group ID):
34 * <pre><code>
35 *   &#64;RestrictTo(GROUP_ID)
36 *   public void resetPaddingToInitialValues() { ...
37 * </code></pre>
38 * Example of restricting usage to tests:
39 * <pre><code>
40 *   &#64;RestrictScope(TESTS)
41 *   public abstract int getUserId();
42 * </code></pre>
43 * Example of restricting usage to subclasses:
44 * <pre><code>
45 *   &#64;RestrictScope(SUBCLASSES)
46 *   public void onDrawForeground(Canvas canvas) { ...
47 * </code></pre>
48 */
49@Retention(CLASS)
50@Target({ANNOTATION_TYPE,TYPE,METHOD,CONSTRUCTOR,FIELD,PACKAGE})
51public @interface RestrictTo {
52
53    /**
54     * The scope to which usage should be restricted.
55     */
56    Scope[] value();
57
58    enum Scope {
59        /**
60         * Restrict usage to code within the same group ID (based on gradle
61         * group ID).
62         */
63        GROUP_ID,
64
65        /**
66         * Restrict usage to tests.
67         */
68        TESTS,
69
70        /**
71         * Restrict usage to subclasses of the enclosing class.
72         * <p>
73         * <strong>Note:</strong> This scope should not be used to annotate
74         * packages.
75         */
76        SUBCLASSES,
77    }
78}
79