Repeatable Annotation

A repeatable annotation in Kotlin is a custom annotation configured with the @kotlin.annotation.Repeatable meta-annotation, allowing it to be applied multiple times to the exact same target element (such as a class, function, or property) within a single declaration.

Declaration and Syntax

To define a repeatable annotation, apply the @Repeatable meta-annotation to an annotation class. Kotlin automatically handles the generation of the underlying container annotation required to group multiple instances.

@Repeatable
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class Tag(val name: String)

Once defined, the annotation can be stacked sequentially on a single target:

@Tag("core")
@Tag("experimental")
class Component

Compiler Mechanics and Retention

When the Kotlin compiler encounters multiple instances of a repeatable annotation, it implicitly generates a container annotation to hold the array of annotation instances.

• Native Support: Since Kotlin 1.6, repeatable annotations are supported natively. The compiler automatically generates a nested Container annotation (e.g., Tag.Container) to hold the array of values.
• Retention Policies: Kotlin’s native @kotlin.annotation.Repeatable fully supports all retention policies, including AnnotationRetention.SOURCE, AnnotationRetention.BINARY, and AnnotationRetention.RUNTIME.

Java Interoperability

Kotlin’s native @kotlin.annotation.Repeatable automatically makes the annotation repeatable in Java. The Kotlin compiler achieves this by implicitly generating the nested Container annotation class, which Java 8+ recognizes as the standard container for the repeatable annotation.

The @JvmRepeatable meta-annotation is only required if you must specify a custom explicit container class. This is typically necessary only for backward compatibility with an existing Java codebase that expects a specific, pre-defined container annotation name rather than Kotlin’s default nested Container.

// 1. Explicitly define a custom container annotation
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS)
annotation class LegacyTagContainer(val value: Array<Tag>)

// 2. Apply @JvmRepeatable and link it to the custom container class
@JvmRepeatable(LegacyTagContainer::class)
@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.CLASS)
annotation class Tag(val name: String)

Runtime Retrieval via Reflection

To extract multiple instances of a repeatable annotation at runtime, use the findAnnotations<T>() extension function from the kotlin.reflect.full package. This function automatically unwraps the implicit or explicit container and returns a list of the annotation instances.

import kotlin.reflect.full.findAnnotations

fun inspectAnnotations() {
    val tags = Component::class.findAnnotations<Tag>()
    
    tags.forEach { tag ->
        println(tag.name)
    }
}
// Output:
// core
// experimental

Master Kotlin with Deep Grasping Methodology!

Learn More