1 /*
2  * Copyright (C) 2022 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 java.lang.annotation.ElementType.CONSTRUCTOR
19 import java.lang.annotation.ElementType.FIELD
20 import java.lang.annotation.ElementType.METHOD
21 import java.lang.annotation.ElementType.PACKAGE
22 import java.lang.annotation.ElementType.TYPE
23 
24 /**
25  * Denotes that the annotated element should only be called if the given extension is at least the
26  * given version.
27  *
28  * This annotation is repeatable, and if specified multiple times, you are required to have one of
29  * (not all of) the specified extension versions.
30  *
31  * Example:
32  * ```
33  * @RequiresExtension(extension = Build.VERSION_CODES.R, version = 3)
34  * fun methodUsingApisFromR() { ... }
35  * ```
36  *
37  * For the special case of [extension] == 0, you can instead use the [RequiresApi] annotation;
38  * `@RequiresApi(30)` is equivalent to `@RequiresExtension(extension=0, version=30)`.
39  */
40 @MustBeDocumented
41 @Retention(AnnotationRetention.BINARY)
42 @Target(
43     AnnotationTarget.ANNOTATION_CLASS,
44     AnnotationTarget.CLASS,
45     AnnotationTarget.FUNCTION,
46     AnnotationTarget.PROPERTY_GETTER,
47     AnnotationTarget.PROPERTY_SETTER,
48     AnnotationTarget.CONSTRUCTOR,
49     AnnotationTarget.FIELD,
50     AnnotationTarget.FILE
51 )
52 // Needed due to Kotlin's lack of PACKAGE annotation target
53 // https://youtrack.jetbrains.com/issue/KT-45921
54 @Suppress("DEPRECATED_JAVA_ANNOTATION", "SupportAnnotationUsage")
55 @java.lang.annotation.Target(TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE)
56 @Repeatable
57 public annotation class RequiresExtension(
58     /**
59      * The extension SDK ID. This corresponds to the extension id's allowed by
60      * [android.os.ext.SdkExtensions.getExtensionVersion], and for id values less than 1_000_000 is
61      * one of the [android.os.Build.VERSION_CODES].
62      */
63     @IntRange(from = 1) val extension: Int,
64     /** The minimum version to require */
65     @IntRange(from = 1) val version: Int
66 )
67