1 /* 2 * Copyright (C) 2023 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.FIELD; 19 import static java.lang.annotation.ElementType.METHOD; 20 import static java.lang.annotation.RetentionPolicy.SOURCE; 21 22 import java.lang.annotation.Documented; 23 import java.lang.annotation.Retention; 24 import java.lang.annotation.Target; 25 26 /** 27 * Denotes that the annotated method checks if the SDK_INT API level is 28 * at least the given value, and either returns it or executes the 29 * given lambda in that case (or if it's a field, has the value true). 30 * 31 * The API level can be specified either as an API level via 32 * {@link #api()}, or for preview platforms as a codename (such as "R") via 33 * {@link #codename()}}, or it can be passed in to the method; in that 34 * case, the parameter containing the API level or code name should 35 * be specified via {@link #parameter()}, where the first parameter 36 * is numbered 0. 37 * 38 * <p> 39 * Examples: 40 * <pre><code> 41 * // Simple version check 42 * @ChecksSdkIntAtLeast(api = Build.VERSION_CODES.O) 43 * public static boolean isAtLeastO() { 44 * return Build.VERSION.SDK_INT >= 26; 45 * } 46 * 47 * // Required API level is passed in as first argument, and function 48 * // in second parameter is executed if SDK_INT is at least that high: 49 * @ChecksSdkIntAtLeast(parameter = 0, lambda = 1) 50 * inline fun fromApi(value: Int, action: () -> Unit) { 51 * if (Build.VERSION.SDK_INT >= value) { 52 * action() 53 * } 54 * } 55 * 56 * // Java field: 57 * @ChecksSdkIntAtLeast(api = Build.VERSION_CODES.LOLLIPOP) 58 * public static final boolean SUPPORTS_LETTER_SPACING = 59 * Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP; 60 * 61 * </code></pre> 62 * 63 * @hide 64 */ 65 @Documented 66 @Retention(SOURCE) 67 @Target({METHOD, FIELD}) 68 public @interface ChecksSdkIntAtLeast { 69 /** 70 * The API level is at least the given level 71 */ api()72 int api() default -1; 73 74 /** 75 * The API level is at least the given codename (such as "R") 76 */ codename()77 String codename() default ""; 78 79 /** 80 * The API level is specified in the given parameter, where the first parameter is number 0 81 */ parameter()82 int parameter() default -1; 83 84 /** 85 * The parameter number for a lambda that will be executed if the API level is at least 86 * the value supplied via {@link #api()}, {@link #codename()} or 87 * {@link #parameter()} 88 */ lambda()89 int lambda() default -1; 90 } 91