Java 8 repeatable custom annotations

Question

I know about basic annotations in Java like @Override etc.

Annotations are only metadata and they do not contain any business logic.

I am going through repeating annotations from Oracle documentation page to understand Java 8 new feature.

For example, you are writing code to use a "timer service that enables you to run a method at a given time or on a certain schedule, similar to the UNIX cron service". Now you want to set a timer to run a method, doPeriodicCleanup, on the last day of the month and on every Friday at 11:00 p.m. To set the timer to run, create an @Schedule annotation and apply it twice to the doPeriodicCleanup method.

@Schedule(dayOfMonth="last")
@Schedule(dayOfWeek="Fri", hour="23")
public void doPeriodicCleanup() { ... }

Declare a Repeatable Annotation Type

The annotation type must be marked with the @Repeatable meta-annotation. The following example defines a custom @Schedule repeatable annotation type:

import java.lang.annotation.Repeatable;

@Repeatable(Schedules.class)
public @interface Schedule {
    String dayOfMonth() default "first";
    String dayOfWeek() default "Mon";
    int hour() default 12;
}

Declare the Containing Annotation Type

The containing annotation type must have a value element with an array type. The component type of the array type must be the repeatable annotation type. The declaration for the Schedules containing annotation type is the following:

public @interface Schedules {
    Schedule[] value();
}

I did not understand use and usage of @Schedules annotation. How does it work for below method now? .

public void doPeriodicCleanup() { ... }

Thanks in advance.

Answer 1

Before Java 8, a given annotation could only be set once on a method (or class, or field, etc.). So, if you wanted to be able to set two different schedules on a single method, you had to define a "wrapping" annotation such as Schedules, containing an array of Schedule annotions.

The developer thus had to do something like this:

@Schedules(value = {
    @Schedule(dayOfMonth="last"),
    @Schedule(dayOfWeek="Fri", hour="23")
})

This is not very readable, and the Schedules annotation doesn't have any purpose other than containing several Schedule annotations.

To reduce the boilerplate, but keep the annotations API identical, it's now allowed to simply annotate the method with

@Schedule(dayOfMonth="last"),
@Schedule(dayOfWeek="Fri", hour="23")

by declaring Schedule as repeatable and specifying its "wrapping" annotation. But it's just syntax sugar, that results in the same thing as the previous code: the method, at runtime, is seen as being annotated with a single Schedules annotation containing two Schedule. The compiler transforms the second piece of code into the first one.