How to understand directly present, indirectly present, present, and associated in java annotation?

In java doc of AnnotatedElement, I read the term : directly present, indirectly present, present, and associated, but I couldn't understand their meaning.

For example, in the doc it says :
>An annotation A is directly present on an element E if E has a RuntimeVisibleAnnotations or RuntimeVisibleParameterAnnotations or RuntimeVisibleTypeAnnotations attribute, and the attribute contains A.

But I don't know what RuntimeVisibleAnnotations attribute is and what's the meaning of "the attribute contains A".

Can someone give some examples to show their difference, thanks!

The Attributes (e.g. RuntimeVisibleAnnotations)

The mentioned attributes are part of the class file format. For instance, the RuntimeVisibleAnnotaitons attribute is described by §4.7.16 of the Java Virtual Machine Specification:

>The RuntimeVisibleAnnotations attribute is a variable-length attribute in the attributes table of a ClassFile, field_info, or method_info structure (§4.1,§4.5, §4.6). The RuntimeVisibleAnnotations attribute records run-time visible annotations on the declaration of the corresponding class, field, or method.
>
>There may be at most one RuntimeVisibleAnnotations attribute in the attributes table of a ClassFile, field_info, or method_info structure.
>
>[...]

You can see this attribute by inspecting the byte code via javap. For example, this:

@FunctionalInterface // has runtime retention
public interface Foo {
  void bar(); // satisfy functional interface requirements
}

Gives this:

public interface Foo
  minor version: 0
  major version: 58
  flags: (0x0601) ACC_PUBLIC, ACC_INTERFACE, ACC_ABSTRACT
  this_class: #1                          // Foo
  super_class: #3                         // java/lang/Object
  interfaces: 0, fields: 0, methods: 1, attributes: 2
Constant pool:
   #1 = Class              #2             // Foo
   #2 = Utf8               Foo
   #3 = Class              #4             // java/lang/Object
   #4 = Utf8               java/lang/Object
   #5 = Utf8               bar
   #6 = Utf8               ()V
   #7 = Utf8               SourceFile
   #8 = Utf8               Foo.java
   #9 = Utf8               RuntimeVisibleAnnotations
  #10 = Utf8               Ljava/lang/FunctionalInterface;
{
  public abstract void bar();
    descriptor: ()V
    flags: (0x0401) ACC_PUBLIC, ACC_ABSTRACT
}
SourceFile: "Foo.java"
RuntimeVisibleAnnotations:
  0: #10()
    java.lang.FunctionalInterface

You can see the RuntimeVisibleAnnotations attribute for the class (interface) Foo at the bottom. That attribute contains a single entry: java.lang.FunctionalInterface. That means said annotation is directly present on Foo.

Kinds of Presence

Let's assume we have the following annotations (imports omitted):

@Retention(RUNTIME)
@Inherited
public @interface Foo {}

@Retention(RUNTIME)
@Inherited
@Repeatable(BarList.class)
public @interface Bar {}

@Retention(RUNTIME)
@Inherited
public @interface BarList {
  Bar[] value();
}

Then if we have:

@Foo
@BarList({@Bar, @Bar})
public class Parent {}

public class Child extends Parent {}

The following is true:

1. Foo is directly present on Parent.
2. Foo is present on Child (because it's inherited)
3. BarList is directly present on Parent
4. BarList is present on Child (because it's inherited)
5. Both Bar annotations are indirectly present on Parent (because they're repeatable and in their container annotation)
6. Both Bar annotations are associated with Child (because they're inherited, repeatable, and in their container annotation)

Some additional notes:

• If an annotation is directly present on E then the annotation is also present on and associated with E

• If an annotation is indirectly present on E then the annotation is also associated with E

• An annotation is inherited if and only if:

  1. The annotation type is meta-annotated with java.lang.annotation.Inherited
  2. The annotation is present on an ancestor class (annotation inheritance only applies to classes, not interfaces, methods, fields, etc.)

• When an annotation is inherited but is present on multiple classes throughout the class hierarchy then only the "most recent" annotation is found (i.e. the annotation closest to the bottom of the queried hierarchy)

• If an annotation is present on class E, but the annotation is not inheritable, then the annotation will not be present on nor associated with subclasses of E

• Repeatable annotations do not need to be explicitly placed in their corresponding container annotation. For example, the above could have used:

  @Foo
  @Bar
  @Bar
  public class Parent {}
  

  The two Bar annotations are implicitly wrapped in their container annotation (i.e. BarList) by the compiler. That means the two Bar annotations are still indirectly present on Parent and associated with Child. However, this implicit wrapping only occurs if there is more than one of a repeatable annotation. So if there were only one Bar annotation then it would be directly present on Parent and present on Child.