Skip to content

AnnotationInfo API

Jump to bottom Edit New page
Luke Hutchison edited this page Aug 16, 2021 · 5 revisions

See also the ClassGraph API overview.

Contents

AnnotationInfo

Holds information about one concrete annotation instance, for an annotation on a class, field, method, or method parameter. Obtained by calling ClassInfo#getAnnotationInfo(), FieldInfo#getAnnotationInfo(), MethodInfo#getAnnotationInfo(), and MethodParameterInfo#getAnnotationInfo().

This is the information about a concrete annotation in the sense that it contains information not just about the annotating class, but also the specific annotation parameters, which may or may not override default annotation parameter values associated with the annotation class.

  • Properties: (N.B. call .enableAnnotationInfo() before .scan() to enable annotation scanning, and call .ignoreAnnotationVisibility() if you want to scan non-public annotations.)
    • .getName() returns the name of the annotation as a String.
    • .getClassInfo() returns the ClassInfo object for the annotation class.
    • .isInherited() returns true if the annotation is meta-annotated with @Inherited, which means the annotation is inherited by the subclasses of annotated classes.
  • Parameters:
  • Classloading:
    • .loadClassAndInstantiate() loads the class returned by .getClassInfo() and returns an Annotation instance that can be cast to the specific annotation type, and that is equivalent to to the specific annotation instance represented by the AnnotationInfo object.
      • This is implemented by dynamically instantiating an InvocationHandler that emulates the annotation instance, pulling annotation parameters (including annotation default parameter values) from the AnnotationInfo object. An InvocationHandler is needed because annotations can't be directly instantiated without also loading the annotated class.

AnnotationParameterValue

Holds an annotation parameter name and value.

  • .getName() returns the name of the annotation parameter as a String.
  • .getValue() returns the annotation parameter value as an Object. May be one of the following types:
    • String for string constants
    • Integer, Long, Short, Boolean, Character, Float, Double or Byte for primitive-typed constants
    • AnnotationEnumValue for enum constants
    • AnnotationClassRef for Class<?> references within annotations
    • AnnotationInfo for nested annotations
    • An array, with element type matching one of the types in this list, for array annotation parameter types.

AnnotationParameterValueList

Extends ArrayList<AnnotationParameterValue> with the following convenience methods:

  • .asMap() returns the AnnotationParameterValueList as a Map<String, AnnotationParameterValue> mapping each annotation parameter name to the corresponding AnnotationParameterValue object.
  • .getNames() returns a list of the names of the annotation parameters in this list, as a List<String>.
  • .getAsStrings() returns a list of the result of calling .toString() on each AnnotationParameterValue object in this list, producing a List<string> of String representations of each annotation parameter name and value.
    • .getAsStringsWithSimpleNames() works like .getAsStrings(), but uses only the simple name of any referenced classes, by calling .toStringWithSimpleNames() on each list element rather than .toString().
  • .containsName(String parameterName) returns true if the list contains an annotation parameter of the requested name.
  • .get(String parameterName) returns the AnnotationParameterValue object in this list with the requested parameter name, or null if not found.
  • .getValue(String parameterName) returns value of the AnnotationParameterValue object in this list with the requested parameter name, by calling AnnotationParameterValue#getValue() on that object, or null if not found.

AnnotationEnumValue

Represents an enum constant in an annotation parameter value.

  • .getClassName() returns the name of the enum class as a String.
  • .getValueName() returns the name of the enum constant value as a String.
  • .getName() returns the fully-qualified name of the enum const value (i.e. getClassName() + "." + getConstValueName()) as a String.
  • .loadClassAndReturnConstValue() loads the enum class, if it has not yet been loaded, instantiates the enum constants, and returns the enum constant represented by this annotation parameter value.

    🛑 Make sure that you are not trying to load classes after the ScanResult goes out of scope or ScanResult#close() is called. The ScanResult must still exist for classloading to succeed.

    • .loadClassAndReturnConstValue(boolean ignoreExceptions) loads the enum class and returns the enum constant value, as above, but also allows you to ignore classloading exceptions (if there is an exception, it returns null instead).

AnnotationClassRef

Represents a Class<?> reference in an annotation parameter value.

  • .getName() returns the name of the referenced class as a String.
  • .getClassInfo() returns the ClassInfo object for the referenced class, if the referenced class was encountered during scanning (causing a ClassInfo object to be created for it). May return null if the referenced class was not encountered during scanning (e.g. if the class was rejected). Even if .getClassInfo() returns null, .loadClass() may still be able to load the class by name.
  • .loadClass() loads the referenced class, if it has not yet been loaded, and returns a Class<?> reference for the loaded class.

    🛑 Make sure that you are not trying to load classes after the ScanResult goes out of scope or ScanResult#close() is called. The ScanResult must still exist for classloading to succeed.

    • .loadClass(boolean ignoreExceptions) loads the referenced class, as above, but also allows you to ignore classloading exceptions (if there is an exception, it returns null instead).

AnnotationInfoList

Extends ArrayList<AnnotationInfo> with the following convenience methods:

  • .asMap() returns the AnnotationInfoList as a Map<String, AnnotationInfo> mapping each annotation name to the corresponding AnnotationInfo object.
  • .directOnly() returns the list of direct annotations, excluding meta-annotations. If this AnnotationInfoList consists of class annotations, i.e. if it was produced by calling ClassInfo#getAnnotationInfo(), then the returned list also excludes annotations inherited from a superclass or implemented interface that was meta-annotated with @java.lang.annotation.Inherited.
  • .getNames() returns a list of the names of the annotations in this list, as a List<String>.
  • .getAsStrings() returns a list of the result of calling .toString() on each AnnotationInfo object in this list, producing a List<string> of String representations of each annotation, including annotation parameters, etc.
  • .containsName(String annotationName) returns true if this list contains an annotation of the requested name.
  • .get(String annotationName) returns the first AnnotationInfo object in this list with the requested name, if present, otherwise returns null. There will only be one annotation in the list with a given name, unless the annotation is a @Repeatable annotation (i.e. unless another class is meta-annotated with @Repeatable, with the repeated annotation's class ref as a parameter).
  • .getRepeatable(String annotationName | Class<?> annotationClassRef) returns all AnnotationInfo objects in this list with the requested annotation name or class, as an AnnotationInfoList otherwise returns the empty list. The returned list will only contain zero or one elements unless the named annotation is @Repeatable.
  • .filter(AnnotationInfoFilter filter) returns an AnnotationInfoList that is a subset of the original list, obtained by applying the given filter predicate to each AnnotationInfo object in the list.
    • AnnotationInfoFilter is a FunctionalInterface with the single abstract method boolean accept(AnnotationInfo annotationInfo).

тест

Add a custom sidebar

Clone this wiki locally