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 */ 16 package androidx.annotation; 17 18 import static java.lang.annotation.ElementType.ANNOTATION_TYPE; 19 import static java.lang.annotation.ElementType.CONSTRUCTOR; 20 import static java.lang.annotation.ElementType.FIELD; 21 import static java.lang.annotation.ElementType.METHOD; 22 import static java.lang.annotation.ElementType.PACKAGE; 23 import static java.lang.annotation.ElementType.TYPE; 24 import static java.lang.annotation.RetentionPolicy.CLASS; 25 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.Target; 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 * @RestrictTo(GROUP_ID) 36 * public void resetPaddingToInitialValues() { ... 37 * </code></pre> 38 * Example of restricting usage to tests: 39 * <pre><code> 40 * @RestrictScope(TESTS) 41 * public abstract int getUserId(); 42 * </code></pre> 43 * Example of restricting usage to subclasses: 44 * <pre><code> 45 * @RestrictScope(SUBCLASSES) 46 * public void onDrawForeground(Canvas canvas) { ... 47 * </code></pre> 48 */ 49 @Retention(CLASS) 50 @Target({ANNOTATION_TYPE,TYPE,METHOD,CONSTRUCTOR,FIELD,PACKAGE}) 51 public @interface RestrictTo { 52 53 /** 54 * The scope to which usage should be restricted. 55 */ value()56 Scope[] value(); 57 58 enum Scope { 59 /** 60 * Restrict usage to code within the same library (e.g. the same 61 * gradle group ID and artifact ID). 62 */ 63 LIBRARY, 64 65 /** 66 * Restrict usage to code within the same group of libraries. 67 * This corresponds to the gradle group ID. 68 */ 69 LIBRARY_GROUP, 70 71 /** 72 * Restrict usage to code within the same group ID (based on gradle 73 * group ID). This is an alias for {@link #LIBRARY_GROUP}. 74 * 75 * @deprecated Use {@link #LIBRARY_GROUP} instead 76 */ 77 @Deprecated 78 GROUP_ID, 79 80 /** 81 * Restrict usage to tests. 82 */ 83 TESTS, 84 85 /** 86 * Restrict usage to subclasses of the enclosing class. 87 * <p> 88 * <strong>Note:</strong> This scope should not be used to annotate 89 * packages. 90 */ 91 SUBCLASSES, 92 } 93 } 94