Аннотация @Retention

Аннотация @Retention определяет политику удержания (retention policy) для пользовательских аннотаций. Она указывает, будет ли аннотация доступна только в исходном коде, сохранится в скомпилированном байт-коде или будет доступна через рефлексию во время выполнения. Принимает один параметр типа AnnotationRetention.

Импорт

import kotlin.annotation.AnnotationRetention
import kotlin.annotation.Retention

Синтаксис

@Retention(AnnotationRetention.SOURCE)
annotation class MyAnnotation

@Retention(AnnotationRetention.BINARY)
annotation class MyAnnotation

@Retention(AnnotationRetention.RUNTIME)
annotation class MyAnnotation

Параметры AnnotationRetention

Тип AnnotationRetention имеет три возможных значения:

SOURCE - аннотация доступна только в исходном коде и не сохраняется в скомпилированном байт-коде
BINARY - аннотация сохраняется в скомпилированном байт-коде, но недоступна через рефлексию во время выполнения
RUNTIME - аннотация сохраняется в скомпилированном байт-коде и доступна через рефлексию во время выполнения

Пример

Создадим аннотацию с политикой удержания только в исходном коде:

@Retention(AnnotationRetention.SOURCE)
annotation class MarkForReview

Такая аннотация будет удалена после компиляции и недоступна во время выполнения.

Пример

Создадим аннотацию с политикой удержания в байт-коде:

@Retention(AnnotationRetention.BINARY)
annotation class Serializable

Аннотация сохранится в скомпилированном классе, но не будет доступна через рефлексию.

Пример

Создадим аннотацию с политикой удержания во время выполнения:

@Retention(AnnotationRetention.RUNTIME)
annotation class ApiEndpoint(val path: String)

Такая аннотация будет доступна через рефлексию и может использоваться для обработки во время выполнения программы.

Пример

Использование аннотации с политикой RUNTIME и проверка через рефлексию:

@Retention(AnnotationRetention.RUNTIME)
annotation class TestCase(val id: Int)

@TestCase(id = 42)
class MyTestClass

val annotation = MyTestClass::class.annotations
	.filterIsInstance<TestCase>()
	.firstOrNull()

println(annotation?.id)

Результат выполнения кода:

Int 42

Значение по умолчанию

Если аннотация @Retention не указана явно, то по умолчанию используется значение RUNTIME. Это отличается от Java, где по умолчанию используется CLASS.

// По умолчанию имеет RetentionPolicy.RUNTIME
annotation class MyAnnotation

Смотрите также

ключевое слово annotation,
которое используется для объявления аннотаций
ключевое слово target,
которое определяет допустимые цели для применения аннотации
ключевое слово repeatable,
которое позволяет применять аннотацию multiple раз к одному элементу