Java Annotations Reflection Ordering

Question

When accessing Annotations defined on a Field via Reflection (i.e using the getDeclaredAnnotations() : Annotation[] method) does the Java 6 or 7 specification make any guarantees about the order in which the Annotations are returned. I have examined the relevant java docs but can't seem to find a definitive answer.

Answer 1

That’s indeed a bit underspecified. Let’s start with the Java 8 feature of repeatable annotations as there are some bits about it:

JLS §9.7.5. Multiple Annotations of the Same Type:

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.

So the container will provide the repeated annotations in order.

Additionally, the documentation of AnnotatedElement specifies:

For an invocation of get[Declared]AnnotationsByType( Class < T >), the order of annotations which are directly or indirectly present on an element E is computed as if indirectly present annotations on E are directly present on E in place of their container annotation, in the order in which they appear in the value element of the container annotation.

Putting these two together, it implies that repeated annotations like @Foo(1) @Foo(2) @Foo(3) are stored like you had written @FooContainer({@Foo(1), @Foo(2), @Foo(3)}) and the latter, regardless of how it was originally created, will be treated by getDeclaredAnnotations() like directly present annotations of that order.

So the answer for repeated annotations is that the order will be the “left-to-right order in which they appeared”.

---

But there is another conclusion we can draw from the documentation of AnnotatedElement. Since it states that the order of annotations is computed as if indirectly present annotations are directly present in place of their container annotation, it implies that if you write @Foo(1) @FooContainer({@Foo(2), @Foo(3)}) or @FooContainer({@Foo(1), @Foo(2)}) @Foo(3), the order will be the same as the elements of the container will replace it just as had you written @Foo(1) @Foo(2) @Foo(3).

It’s interesting, how that is achieved:

If annotations of the annotation type annotationClass are found to be both directly and indirectly present, then getDeclaredAnnotations() will get called to determine the order of the elements in the returned array.

This implementation note is the first indicator within the entire documentation that getDeclaredAnnotations() has a reliable order. It is used to determine the order that is required to fulfill the contract described above.

So the answer is, yes, getDeclaredAnnotations() provides the annotations in a guaranteed order, but that information is not directly attached to the documentation of the method itself.

This is derived from the Java 8 documentation, but since Java 6 and 7 reached their end-of-life now and won’t change, the fact that the observed behavior of the their implementation matches the behavior that is guaranteed at least for Java 8, might be enough to rely on it.