XAnnotated.kt
/*
* Copyright 2020 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.room.compiler.processing
import kotlin.reflect.KClass
/**
* Common interface implemented by elements that might have annotations.
*/
interface XAnnotated {
/**
* Gets the list of annotations with the given type.
*
* For repeated annotations declared in Java code, please use the repeated annotation type,
* not the container. Calling this method with a container annotation will have inconsistent
* behaviour between Java AP and KSP.
*
* @see [hasAnnotation]
* @see [hasAnnotationWithPackage]
*/
fun <T : Annotation> getAnnotations(
annotation: KClass<T>
): List<XAnnotationBox<T>>
/**
* Returns all annotations on this element represented as [XAnnotation].
*
* As opposed to other functions like [getAnnotations] this does not require you to have a
* reference to each annotation class, and thus it can represent annotations in the module
* sources being compiled. However, note that the returned [XAnnotation] cannot provide
* an instance of the annotation (like [XAnnotationBox.value] can) and instead all values
* must be accessed dynamically.
*
* The returned [XAnnotation]s can be converted to [XAnnotationBox] via
* [XAnnotation.asAnnotationBox] if the annotation class is on the class path.
*/
fun getAllAnnotations(): List<XAnnotation>
/**
* Returns `true` if this element is annotated with the given [annotation].
*
* For repeated annotations declared in Java code, please use the repeated annotation type,
* not the container. Calling this method with a container annotation will have inconsistent
* behaviour between Java AP and KSP.
* @see [hasAnyOf]
*/
fun hasAnnotation(
annotation: KClass<out Annotation>
): Boolean
/**
* Returns `true` if this element has an annotation that is declared in the given package.
* Alternatively, all annotations can be accessed with [getAllAnnotations].
*/
fun hasAnnotationWithPackage(pkg: String): Boolean
/**
* Returns `true` if this element has one of the [annotations].
*/
fun hasAnyOf(vararg annotations: KClass<out Annotation>) = annotations.any(this::hasAnnotation)
@Deprecated(
replaceWith = ReplaceWith("getAnnotation(annotation)"),
message = "Use getAnnotation(not repeatable) or getAnnotations (repeatable)"
)
fun <T : Annotation> toAnnotationBox(annotation: KClass<T>): XAnnotationBox<T>? =
getAnnotation(annotation)
/**
* If the current element has an annotation with the given [annotation] class, a boxed instance
* of it will be returned where fields can be read. Otherwise, `null` value is returned.
*
* @see [hasAnnotation]
* @see [getAnnotations]
* @see [hasAnnotationWithPackage]
*/
fun <T : Annotation> getAnnotation(annotation: KClass<T>): XAnnotationBox<T>? {
return getAnnotations(annotation).firstOrNull()
}
}