Interface AnnotationTarget

All Known Subinterfaces:
AnnotationDescriptor<A>, AnnotationTargetSupport, ClassDetails, ClassDetailsSupport, FieldDetails, MemberDetails, MethodDetails, MutableAnnotationDescriptor<A,C>, MutableAnnotationTarget, MutableClassDetails, MutableMemberDetails, RecordComponentDetails
All Known Implementing Classes:
AbstractAnnotationDescriptor, AbstractAnnotationTarget, AbstractAnnotationTarget, AbstractJdkAnnotationTarget, DynamicClassDetails, DynamicFieldDetails, JdkClassDetails, JdkFieldDetails, JdkMethodDetails, JdkRecordComponentDetails, MissingPackageInfoDetails, OrmAnnotationDescriptor, SimpleClassDetails, StandardAnnotationDescriptor
public interface AnnotationTarget
Abstract for something where an annotation can be used.
See Also:

  • Method Details

    • getKind

      AnnotationTarget.Kind getKind()
      The kind of target

    • getName

      String getName()
      A descriptive name for the target used mostly for logging

    • getContainer

      ClassDetails getContainer(ModelsContext modelsContext)
      Get the ClassDetails for the class which is the "container" for this target.
      • For a member (org.hib.Thing#id), this will be the declaring type (org.hib.Thing).
      • For a class (org.hib.Thing), this will be the ClassDetails for its package (org.hib.package-info)
      • For a package (org.hib.package-info), this will be the ClassDetails for the containing package (org.package-info)
      API Note:
      If not already, this resolution should be registered into the context's class registry

    • walkContainers

      default void walkContainers(boolean crossPackageBoundaries, ModelsContext modelContext, Consumer<ClassDetails> consumer)
      Walk "up" containers from this target.
      Parameters:
      crossPackageBoundaries - If this target is a package, should we walk to its container?
      modelContext - Access to useful stuff.
      consumer - Consumer of the containers

    • walkSelfAndContainers

      default void walkSelfAndContainers(boolean crossPackageBoundaries, ModelsContext modelContext, Consumer<AnnotationTarget> consumer)
      Walk "up" containers from this target.
      Parameters:
      crossPackageBoundaries - If this target is a package, should we walk to its container?
      modelContext - Access to useful stuff.
      consumer - Consumer of the containers

    • fromContainers

      default <T> T fromContainers(boolean crossPackageBoundaries, ModelsContext modelContext, Function<ClassDetails, T> matchingExtractor)
      Walk "up" containers from this target.
      Parameters:
      crossPackageBoundaries - If this target is a package, should we walk to its container?
      modelContext - Access to useful stuff.
      matchingExtractor - A function that acts as an extractor against a container. A non-null return indicates a match, which will be the return from this method.

    • fromSelfAndContainers

      default <T> T fromSelfAndContainers(boolean crossPackageBoundaries, ModelsContext modelContext, Function<AnnotationTarget, T> matchingExtractor)
      Walk "up" containers from this target.
      Parameters:
      crossPackageBoundaries - If this target is a package, should we walk to its container?
      modelContext - Access to useful stuff.
      matchingExtractor - A function that acts as an extractor against a container. A non-null return indicates a match, which will be the return from this method.

    • getDirectAnnotationUsages

      Collection<? extends Annotation> getDirectAnnotationUsages()
      Access to all the annotations used on this target.
      API Note:
      This returns the usages directly available on the target; it does not expand repeatable containers (e.g. NamedQueries -> *NamedQuery).

    • forEachDirectAnnotationUsage

      default void forEachDirectAnnotationUsage(Consumer<? extends Annotation> consumer)
      Allows to visit every annotation on the target.
      API Note:
      Only visits the usages directly available on the target; it does not visit across repeatable containers (e.g. NamedQueries -> *NamedQuery).

    • hasDirectAnnotationUsage

      <A extends Annotation> boolean hasDirectAnnotationUsage(Class<A> type)
      Whether the given annotation is used on this target.
      See Also:
      API Note:
      This form does not check across repeatable containers. E.g., calling this method with NamedQuery will return false when the target directly has a NamedQueries.

    • getDirectAnnotationUsage

      <A extends Annotation> A getDirectAnnotationUsage(AnnotationDescriptor<A> descriptor)
      Form of getAnnotationUsage(AnnotationDescriptor, ModelsContext) which returns null instead of throwing AnnotationAccessException when more than one usage of the requested annotation exists.

    • getDirectAnnotationUsage

      <A extends Annotation> A getDirectAnnotationUsage(Class<A> type)
      Form of getDirectAnnotationUsage(AnnotationDescriptor) accepting the annotation Class

    • hasAnnotationUsage

      <A extends Annotation> boolean hasAnnotationUsage(Class<A> type, ModelsContext modelContext)
      Whether the given annotation is used on this target.
      See Also:
      API Note:
      This forms does check across repeatable containers. E.g., calling this method with NamedQuery will return true when the target directly has a NamedQueries.

    • getAnnotationUsage

      <A extends Annotation> A getAnnotationUsage(AnnotationDescriptor<A> descriptor, ModelsContext modelContext)
      Get the usage of the given annotation on this target.

      For repeatable annotation types (e.g. @NamedQuery), this method will either-

      • if a single repeatable annotation itself is present, it is returned.
      • if the "containing annotation" is present (e.g. @NamedQueries),
        • if the container contains just a single repeatable, that one is returned
        • if the container contains multiple repeatables, AnnotationAccessException will be thrown

      For also checking across meta-annotations, see locateAnnotationUsage(Class, ModelsContext).

      Returns:
      The usage or null

    • getAnnotationUsage

      default <A extends Annotation> A getAnnotationUsage(Class<A> type, ModelsContext modelContext)
      Form of getAnnotationUsage(AnnotationDescriptor, ModelsContext) accepting the annotation Class

    • locateAnnotationUsage

      <A extends Annotation> A locateAnnotationUsage(Class<A> type, ModelsContext modelContext)
      Form of getAnnotationUsage(AnnotationDescriptor, ModelsContext) which also considers meta-annotations - annotations on the classes of each local annotation.

    • getRepeatedAnnotationUsages

      <A extends Annotation> A[] getRepeatedAnnotationUsages(AnnotationDescriptor<A> type, ModelsContext modelContext)
      Get all usages of the specified annotationType in this scope.
      API Note:
      For repeatable annotation types (e.g. @NamedQuery), the returned list will contain the union of
      1. the singular @NamedQuery usage
      2. the nested @NamedQuery usages from the @NamedQueries usage

    • getRepeatedAnnotationUsages

      default <A extends Annotation> A[] getRepeatedAnnotationUsages(Class<A> type, ModelsContext modelContext)
      Form of getRepeatedAnnotationUsages(AnnotationDescriptor, ModelsContext) accepting the annotation Class

    • forEachRepeatedAnnotationUsages

      <A extends Annotation, C extends Annotation> void forEachRepeatedAnnotationUsages(Class<A> repeatable, Class<C> container, ModelsContext modelContext, Consumer<A> consumer)

    • forEachRepeatedAnnotationUsages

      default <A extends Annotation, C extends Annotation> void forEachRepeatedAnnotationUsages(AnnotationDescriptor<A> repeatable, ModelsContext modelContext, Consumer<A> consumer)

    • forEachAnnotationUsage

      default <X extends Annotation> void forEachAnnotationUsage(AnnotationDescriptor<X> type, ModelsContext modelContext, Consumer<X> consumer)
      Call the consumer for each usage of the given type.
      API Note:
      For repeatable annotation types, the consumer will also be called for those defined on the container.

    • forEachAnnotationUsage

      default <X extends Annotation> void forEachAnnotationUsage(Class<X> type, ModelsContext modelContext, Consumer<X> consumer)
      Form of forEachAnnotationUsage(AnnotationDescriptor, ModelsContext, Consumer) accepting the annotation Class

    • getMetaAnnotated

      <A extends Annotation> List<? extends Annotation> getMetaAnnotated(Class<A> metaAnnotationType, ModelsContext modelContext)
      Returns all Annotation usages from this target where the usage's annotation class is annotated with the given metaAnnotationType.

      E.g., given the following class and annotations 

          @interface TheMeta {
        ...
    }

    @TheMeta(...)
    @interface TheAnnotation {
        ...
    }

    @TheAnnotation
    class TheClass {
        ...
    }
      a call to this method passing TheMeta on ClassDetails(TheClass) will return the usage of @TheAnnotation on TheClass.
      API Note:
      This method does not check across repeatable containers. Although the return is a List, we are functionally wanting just the unique ones.

    • getNamedAnnotationUsage

      default <X extends Annotation> X getNamedAnnotationUsage(AnnotationDescriptor<X> type, String matchName, ModelsContext modelContext)
      Get a usage of the given annotation type whose attributeToMatch attribute value matches the given matchName.
      Parameters:
      matchName - The name to match.

    • getNamedAnnotationUsage

      default <X extends Annotation> X getNamedAnnotationUsage(Class<X> type, String matchName, ModelsContext modelContext)
      Helper form of getNamedAnnotationUsage(AnnotationDescriptor, String, ModelsContext)

    • getNamedAnnotationUsage

      <X extends Annotation> X getNamedAnnotationUsage(AnnotationDescriptor<X> type, String matchName, String attributeToMatch, ModelsContext modelContext)
      Get a usage of the given annotation type whose attributeToMatch attribute value matches the given matchName.
      Parameters:
      matchName - The name to match.
      attributeToMatch - Name of the attribute to match on.

    • getNamedAnnotationUsage

      <X extends Annotation> X getNamedAnnotationUsage(Class<X> type, String matchName, String attributeToMatch, ModelsContext modelContext)
      Helper form of getNamedAnnotationUsage(AnnotationDescriptor, String, String, ModelsContext)

    • fromAnnotations

      default <T, A extends Annotation> T fromAnnotations(Class<A> annotationType, AnnotationTarget.AnnotationUsageProcessor<T,A> processor, ModelsContext modelContext)
      Returns a "matching value" using the passed processor from the annotations, of the passed annotationType, used on the target.
      Type Parameters:
      T - The type of the value being returned.
      A - The type of annotations to check
      Returns:
      The matching value or null
      API Note:
      In the case of repeatable annotations, the first usage for which the passed processor does not return null will be returned.

    • asAnnotationDescriptor

      <A extends Annotation> AnnotationDescriptor<A> asAnnotationDescriptor()
      Safe cast method for cases when the target is an annotation.
      Throws:
      IllegalCastException - If the target is not an annotation

    • asClassDetails

      ClassDetails asClassDetails()
      Safe cast method for cases when the target is a class.
      Throws:
      IllegalCastException - If the target is not a class

    • asMemberDetails

      MemberDetails asMemberDetails()
      Safe cast method for cases when the target is a field, method or record component.
      Throws:
      IllegalCastException - If the target is not a member

    • asFieldDetails

      FieldDetails asFieldDetails()
      Safe cast method for cases when the target is a field.
      Throws:
      IllegalCastException - If the target is not a field

    • asMethodDetails

      MethodDetails asMethodDetails()
      Safe cast method for cases when the target is a method.
      Throws:
      IllegalCastException - If the target is not a method

    • asRecordComponentDetails

      RecordComponentDetails asRecordComponentDetails()
      Safe cast method for cases when the target is a record component.
      Throws:
      IllegalCastException - If the target is not a record component