Retention Annotation

The @Retention meta-annotation determines the lifecycle of a custom annotation, specifically dictating whether the annotation is discarded during compilation, stored in the compiled binary, or made accessible to the reflection API during program execution.

In Kotlin, retention policies are defined by the AnnotationRetention enum, which provides three distinct levels of visibility:

• AnnotationRetention.SOURCE: The annotation exists only in the .kt source files. It is stripped out by the compiler and is entirely absent from the resulting .class files.
• AnnotationRetention.BINARY: The annotation is preserved in the compiled .class files but is not loaded into the JVM at runtime. It cannot be accessed via reflection. This is analogous to Java’s RetentionPolicy.CLASS.
• AnnotationRetention.RUNTIME: The annotation is preserved in the compiled .class files and is loaded into the JVM, making it fully queryable at runtime using the Kotlin reflection API.

@Retention(AnnotationRetention.SOURCE)
annotation class SourceLevelAnnotation

@Retention(AnnotationRetention.BINARY)
annotation class BinaryLevelAnnotation

@Retention(AnnotationRetention.RUNTIME)
annotation class RuntimeLevelAnnotation

If a custom annotation is declared without an explicit @Retention meta-annotation, Kotlin implicitly applies AnnotationRetention.RUNTIME as the default behavior.

// Implicitly retains AnnotationRetention.RUNTIME
annotation class DefaultRetentionAnnotation

Master Kotlin with Deep Grasping Methodology!

Learn More