Order of automatically wrapped @Repeatable annotations

Question

Before, I used to declare a wrapper annotation by hand, with an array, and then call it like so:

@Foos({ @Foo(0), @Foo(1), @Foo(2) })
public void bar() {}

Since I was making an array with the { ... } initializers, it was more than clear that the order was to be the same of the declaration when I accessed this method later via Reflection.

However, when I use the new @Repeatable annotation from Java 8, do I have guarantee that the order will be kept?

I declared a simple set of annotations:

public @interface Foos {
  Foo[] value();
}

@Repeatable(Foos.class)
public @interface Foo {
 int value();
} 

and run some tests with the most diverse scenarios:

@Foo(0) @Foo(1) @Foo(2)
public void bar1() {}

@Foo(2)
@Deprecated @Foo(5)
@Foo(10)
public void bar2() {}

and everything seems to work flawlessly (when accessing via Reflection), but I would not like to rely on undocumented stuff. It seems obvious to me that that should be the case, but I can't find it anywhere! Can anyone shed a light on this?

Answer 1

Here's what the Java Language Specification says:

If a declaration context or type context has multiple annotations of a repeatable annotation type T, then it is as if the context has no explicitly declared annotations of type T and one implicitly declared annotation of the containing annotation type of T.

The implicitly declared annotation is called the container annotation, and the multiple annotations of type T which appeared in the context are called the base annotations. The elements of the (array-typed) value element of the container annotation are all the base annotations in the left-to-right order in which they appeared in the context.

(emphasis mine)

So yes, the order of the annotations in the container annotation is the same as the order of declaration of the repeatable annotations.