Interface AnnotationOverlay

All Known Subinterfaces:
MutableAnnotationOverlay
All Known Implementing Classes:
AnnotationOverlayImpl, MutableAnnotationOverlayImpl

public interface AnnotationOverlay
Annotation overlay allows overriding annotation information from an index. This is useful when Jandex is used as a language model and annotations are directly used as framework metadata. Transforming metadata is a frequent requirement in such situations, but core Jandex is immutable. This interface is layered on top of core Jandex and provides the necessary indirection between the user and the core Jandex that is required to apply the transformations.
Since:
3.2.0
  • Method Details

    • builder

      static AnnotationOverlay.Builder builder(IndexView index, Collection<AnnotationTransformation> annotationTransformations)
      Returns a new builder for an annotation overlay for given index and a given collection of transformations.

      Thread safety

      The object returned by the builder is immutable and can be shared between threads without safe publication.

      Parameters:
      index - the Jandex index, must not be null
      annotationTransformations - the collection of annotation transformations
      Returns:
      the annotation overlay builder, never null
    • index

      IndexView index()
      Returns the index whose annotation information is being overlaid.
      Returns:
      the index underlying this annotation overlay, never null
    • hasAnnotation

      boolean hasAnnotation(Declaration declaration, DotName name)
      Returns whether an annotation instance with given name is declared on given declaration.

      Like AnnotationTarget.hasDeclaredAnnotation(DotName), and unlike AnnotationTarget.hasAnnotation(DotName), this method ignores annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      name - name of the annotation type to look for, must not be null
      Returns:
      true if the annotation is present, false otherwise
    • hasAnnotation

      default boolean hasAnnotation(Declaration declaration, Class<? extends Annotation> clazz)
      Returns whether an annotation instance of given clazz is declared on given declaration.

      Like AnnotationTarget.hasDeclaredAnnotation(Class), and unlike AnnotationTarget.hasAnnotation(Class), this method ignores annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      clazz - the annotation type to look for, must not be null
      Returns:
      true if the annotation is present, false otherwise
      See Also:
    • hasAnyAnnotation

      boolean hasAnyAnnotation(Declaration declaration, Set<DotName> names)
      Returns whether any annotation instance with one of given names is declared on given declaration.

      This method ignores annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      names - names of the annotation types to look for, must not be null
      Returns:
      true if any of the annotations is present, false otherwise
    • hasAnyAnnotation

      default boolean hasAnyAnnotation(Declaration declaration, Class<? extends Annotation>... classes)
      Returns whether any annotation instance of one of given classes is declared on given declaration.

      This method ignores annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      classes - annotation types to look for, must not be null
      Returns:
      true if any of the annotations is present, false otherwise
    • annotation

      AnnotationInstance annotation(Declaration declaration, DotName name)
      Returns the annotation instance with given name declared on given declaration.

      Like AnnotationTarget.declaredAnnotation(DotName), and unlike AnnotationTarget.annotation(DotName), this method doesn't return annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods. In such case, if more than one annotation of given name is present, an unspecified instance is returned.

      Parameters:
      declaration - the declaration to inspect, must not be null
      name - name of the annotation type to look for, must not be null
      Returns:
      the annotation instance, or null if not found
    • annotation

      default AnnotationInstance annotation(Declaration declaration, Class<? extends Annotation> clazz)
      Returns the annotation instance of given clazz declared on given declaration.

      Like AnnotationTarget.declaredAnnotation(Class), and unlike AnnotationTarget.annotation(Class), this method doesn't return annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods. In such case, if more than one annotation of given clazz is present, an unspecified instance is returned.

      Parameters:
      declaration - the declaration to inspect, must not be null
      clazz - the annotation type to look for, must not be null
      Returns:
      the annotation instance, or null if not found
      See Also:
    • annotationsWithRepeatable

      Collection<AnnotationInstance> annotationsWithRepeatable(Declaration declaration, DotName name)
      Returns the annotation instances with given name declared on given declaration. If the specified annotation is repeatable, the result also contains all values from the container annotation instance.

      The annotation class must be present in the index underlying this annotation overlay.

      Like AnnotationTarget.declaredAnnotationsWithRepeatable(DotName, IndexView), and unlike AnnotationTarget.annotationsWithRepeatable(DotName, IndexView), this method doesn't return annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      name - name of the annotation type, must not be null
      Returns:
      immutable collection of annotation instances, never null
    • annotationsWithRepeatable

      default Collection<AnnotationInstance> annotationsWithRepeatable(Declaration declaration, Class<? extends Annotation> clazz)
      Returns the annotation instances of given type (clazz) declared on given declaration. If the specified annotation is repeatable, the result also contains all values from the container annotation instance.

      The annotation class must be present in the index underlying this annotation overlay.

      Like AnnotationTarget.declaredAnnotationsWithRepeatable(Class, IndexView), and unlike AnnotationTarget.annotationsWithRepeatable(Class, IndexView), this method doesn't return annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      clazz - the annotation type, must not be null
      Returns:
      immutable collection of annotation instances, never null
      See Also:
    • annotations

      Collection<AnnotationInstance> annotations(Declaration declaration)
      Returns the annotation instances declared on given declaration.

      Like AnnotationTarget.declaredAnnotations(), and unlike AnnotationTarget.annotations(), this method doesn't return annotations declared on nested annotation targets. This doesn't hold in case of methods in the compatible mode, where method parameters are considered part of methods.

      Parameters:
      declaration - the declaration to inspect, must not be null
      Returns:
      immutable collection of annotation instances, never null