How do repeatable annotations work in Java (using @Repeatable), and what problem do they solve?

Prior to Java 8, applying the same annotation type multiple times to one element wasn't allowed; @Repeatable (introduced in Java 8) lets you define a container annotation holding an array of the repeatable annotation, allowing multiple instances of the same annotation type to be applied to a single element -- the compiler handles the wrapping/unwrapping automatically, letting reflection code retrieve either the individual repeated annotations or the container transparently via getAnnotationsByType().

@Retention(RetentionPolicy.RUNTIME)
@Repeatable(Schedules.class)
public @interface Schedule {
    String day();
}

@Retention(RetentionPolicy.RUNTIME)
public @interface Schedules {
    Schedule[] value();
}

public class Job {
    @Schedule(day = "MONDAY")
    @Schedule(day = "FRIDAY")
    public void run() { }
}