Package org.checkerframework.javacutil

Class AnnotationUtils

  • public class AnnotationUtils
extends java.lang.Object
    A utility class for working with annotations.

    Note: AnnotationMirrors are immutable.

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static @BinaryName java.lang.String annotationBinaryName​(javax.lang.model.element.AnnotationMirror annotation)
      Returns the binary name of an annotation as a String.
      static java.lang.Class<?> annotationMirrorToClass​(javax.lang.model.element.AnnotationMirror am)
      Converts an AnnotationMirror to a Class.
      static @CanonicalName java.lang.String annotationName​(javax.lang.model.element.AnnotationMirror annotation)
      Returns the fully-qualified name of an annotation as a String.
      static boolean annotationValueContains​(@Nullable javax.lang.model.element.AnnotationValue avList, java.lang.String s)
      Returns true if an AnnotationValue list contains the given value.
      static boolean annotationValueContains​(java.util.List<? extends javax.lang.model.element.AnnotationValue> avList, java.lang.String s)
      Returns true if an AnnotationValue list contains the given value.
      static boolean annotationValueContainsToString​(@Nullable javax.lang.model.element.AnnotationValue avList, java.lang.String s)
      Returns true if an AnnotationValue list contains a value whose toString() is the given string.
      static boolean annotationValueContainsToString​(java.util.List<? extends javax.lang.model.element.AnnotationValue> avList, java.lang.String s)
      Returns true if an AnnotationValue list contains a value whose toString() is the given string.
      static <T extends java.lang.Enum<T>>
      T[]      		 annotationValueListToEnumArray​(java.util.List<javax.lang.model.element.AnnotationValue> la, java.lang.Class<T> expectedType)
      Converts a list of AnnotationValue to an array of enum.
      static <T extends java.lang.Enum<T>>
      T[]      		 annotationValueListToEnumArray​(javax.lang.model.element.AnnotationValue avList, java.lang.Class<T> expectedType)
      Converts a list of AnnotationValue to an array of enum.
      static <T> java.util.List<T> annotationValueToList​(java.util.List<? extends javax.lang.model.element.AnnotationValue> avList, java.lang.Class<T> expectedType)
      Converts an annotation value to a list.
      static <T> java.util.List<T> annotationValueToList​(javax.lang.model.element.AnnotationValue avList, java.lang.Class<T> expectedType)
      Converts an annotation value to a list.
      static boolean areSame​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c1, java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c2)
      Checks that two collections contain the same annotations.
      static boolean areSame​(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2)
      Returns true iff both annotations are of the same type and have the same annotation values.
      static boolean areSameByClass​(javax.lang.model.element.AnnotationMirror am, java.lang.Class<? extends java.lang.annotation.Annotation> annoClass)
      Deprecated.
      use AnnotatedTypeFactory#areSameByClass or areSameByName(javax.lang.model.element.AnnotationMirror, javax.lang.model.element.AnnotationMirror)
      static boolean areSameByName​(javax.lang.model.element.AnnotationMirror am, java.lang.String aname)
      Checks that the annotation am has the name aname (a fully-qualified type name).
      static boolean areSameByName​(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2)
      Return true iff a1 and a2 have the same annotation type.
      static int compareAnnotationMirrors​(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2)
      Provide an ordering for AnnotationMirrors.
      static int compareByName​(javax.lang.model.element.AnnotationMirror a1, javax.lang.model.element.AnnotationMirror a2)
      Return -1, 0, or 1 depending on whether the name of a1 is less, equal to, or greater than that of a2 (lexicographically).
      static boolean containsSame​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, javax.lang.model.element.AnnotationMirror anno)
      Checks that the collection contains the annotation.
      static boolean containsSameByClass​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.Class<? extends java.lang.annotation.Annotation> anno)
      Checks that the collection contains the annotation.
      static boolean containsSameByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.String anno)
      Checks that the collection contains an annotation of the given name.
      static boolean containsSameByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, javax.lang.model.element.AnnotationMirror anno)
      Checks that the collection contains an annotation of the given name.
      static @Nullable javax.lang.model.element.AnnotationMirror getAnnotationByClass​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.Class<? extends java.lang.annotation.Annotation> anno)
      Returns the AnnotationMirror in c that has the same class as anno.
      static @Nullable javax.lang.model.element.AnnotationMirror getAnnotationByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, java.lang.String anno)
      Returns the AnnotationMirror in c that has the same name as anno.
      static java.util.EnumSet<javax.lang.model.element.ElementKind> getElementKindsForElementType​(java.lang.annotation.ElementType elementType)
      Returns the set of ElementKinds corresponding to elementType.
      static java.util.EnumSet<javax.lang.model.element.ElementKind> getElementKindsForTarget​(@Nullable java.lang.annotation.Target target)
      Returns the set of ElementKinds to which target applies, ignoring TYPE_USE.
      static <T> T getElementValue​(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence elementName, java.lang.Class<T> expectedType, boolean useDefaults)
      Deprecated.
      use getElementValue(AnnotationMirror, ExecutableElement, Class) or getElementValue(AnnotationMirror, ExecutableElement, Class, Object)
      static <T> T getElementValue​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType)
      Get the given element of the annotation anno.
      static <T> T getElementValue​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType, T defaultValue)
      Get the given element of the annotation anno.
      static <T> java.util.List<T> getElementValueArray​(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence elementName, java.lang.Class<T> expectedType, boolean useDefaults)
      Deprecated.
      use #getElementValueArray(AnnotationMirror, ExecutableElement, Class) or #getElementValueArray(AnnotationMirror, ExecutableElement, Class, Object)
      static <T> java.util.List<T> getElementValueArray​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType)
      Get the given element of the annotation anno, where the element has an array type.
      static <T> java.util.List<T> getElementValueArray​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType, java.util.List<T> defaultValue)
      Get the given element of the annotation anno, where the element has an array type.
      static <T> @Nullable java.util.List<T> getElementValueArrayOrNull​(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence elementName, java.lang.Class<T> expectedType, boolean useDefaults)
      Get the element with the name elementName of the annotation anno, or return null if no such element exists.
      static boolean getElementValueBoolean​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, boolean defaultValue)
      Get the given boolean element of the annotation anno.
      static @CanonicalName javax.lang.model.element.Name getElementValueClassName​(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence elementName, boolean useDefaults)
      Deprecated.
      use an ExecutableElement
      static @CanonicalName javax.lang.model.element.Name getElementValueClassName​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element)
      Get the Name of the class that is referenced by element element.
      static java.util.List<@CanonicalName javax.lang.model.element.Name> getElementValueClassNames​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element)
      Get the list of Names of the classes that are referenced by element element.
      static <T extends java.lang.Enum<T>>
      T      		 getElementValueEnum​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType)
      Get the element with the name name of the annotation anno.
      static <T extends java.lang.Enum<T>>
      T      		 getElementValueEnum​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType, T defaultValue)
      Get the element with the name name of the annotation anno.
      static <T extends java.lang.Enum<T>>
      T[]      		 getElementValueEnumArray​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType)
      Get the element with the name name of the annotation anno.
      static <T extends java.lang.Enum<T>>
      T[]      		 getElementValueEnumArray​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, java.lang.Class<T> expectedType, T[] defaultValue)
      Get the element with the name name of the annotation anno.
      static int getElementValueInt​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element)
      Get the given integer element of the annotation anno.
      static int getElementValueInt​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, int defaultValue)
      Get the given integer element of the annotation anno.
      static long getElementValueLong​(javax.lang.model.element.AnnotationMirror anno, javax.lang.model.element.ExecutableElement element, long defaultValue)
      Get the given long element of the annotation anno.
      static <T> @Nullable T getElementValueOrNull​(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence elementName, java.lang.Class<T> expectedType, boolean useDefaults)
      Get the element with the name elementName of the annotation anno, or return null if no such element exists.
      static AnnotationMirrorSet getExplicitAnnotationsOnConstructorResult​(com.sun.source.tree.MethodTree constructorDeclaration)
      Returns the annotations explicitly written on a constructor result.
      static @Nullable javax.lang.model.element.AnnotationMirror getSame​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, javax.lang.model.element.AnnotationMirror anno)
      Returns the AnnotationMirror in c that is the same annotation as anno.
      static @Nullable javax.lang.model.element.AnnotationMirror getSameByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, javax.lang.model.element.AnnotationMirror anno)
      Returns the AnnotationMirror in c that is the same annotation as anno ignoring values.
      static boolean hasInheritedMeta​(javax.lang.model.element.AnnotationMirror anno)
      Returns true if the given annotation has a @Inherited meta-annotation.
      static boolean hasTypeQualifierElementTypes​(java.lang.annotation.ElementType[] elements, java.lang.Class<?> cls)
      Returns true if the given array contains ElementType.TYPE_USE, false otherwise.
      static boolean isDeclarationAnnotation​(javax.lang.model.element.AnnotationMirror anno)
      Returns true if anno is a declaration annotation.
      static boolean sameAnnotationValue​(javax.lang.model.element.AnnotationValue av1, javax.lang.model.element.AnnotationValue av2)
      Return true iff the two AnnotationValue objects are the same.
      static boolean sameElementValues​(javax.lang.model.element.AnnotationMirror am1, javax.lang.model.element.AnnotationMirror am2)
      Returns true if the two annotations have the same elements (fields).
      static java.lang.String toStringSimple​(javax.lang.model.element.AnnotationMirror am)
      Returns a string representation of the annotation mirror, using simple (not fully-qualified) names.
      static void toStringSimple​(javax.lang.model.element.AnnotationMirror am, java.lang.StringBuilder sb)
      Appends a string representation of the annotation mirror, using simple (not fully-qualified) names, to the StringBuilder.
      static java.lang.String toStringSimple​(AnnotationMirrorSet annos)
      Returns a string representation of the annotation mirrors, using simple (not fully-qualified) names.
      static <T extends @NonNull java.lang.Object>
      void      		 updateMappingToImmutableSet​(java.util.Map<T,​AnnotationMirrorSet> map, T key, AnnotationMirrorSet newQual)
      Update a map, to add newQual to the set that key maps to.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • annotationName

        public static final @CanonicalName java.lang.String annotationName​(javax.lang.model.element.AnnotationMirror annotation)
        Returns the fully-qualified name of an annotation as a String.
        Parameters:
        annotation - the annotation whose name to return
        Returns:
        the fully-qualified name of an annotation as a String

      • annotationBinaryName

        public static final @BinaryName java.lang.String annotationBinaryName​(javax.lang.model.element.AnnotationMirror annotation)
        Returns the binary name of an annotation as a String.
        Parameters:
        annotation - the annotation whose binary name to return
        Returns:
        the binary name of an annotation as a String

      • areSame

        @EqualsMethod
public static boolean areSame​(javax.lang.model.element.AnnotationMirror a1,
                              javax.lang.model.element.AnnotationMirror a2)
        Returns true iff both annotations are of the same type and have the same annotation values.

        This behavior differs from AnnotationMirror.equals(Object). The equals method returns true iff both annotations are the same and annotate the same annotation target (e.g. field, variable, etc) -- that is, if its arguments are the same annotation instance.

        Parameters:
        a1 - the first AnnotationMirror to compare
        a2 - the second AnnotationMirror to compare
        Returns:
        true iff a1 and a2 are the same annotation

      • compareByName

        @EqualsMethod
public static int compareByName​(javax.lang.model.element.AnnotationMirror a1,
                                javax.lang.model.element.AnnotationMirror a2)
        Return -1, 0, or 1 depending on whether the name of a1 is less, equal to, or greater than that of a2 (lexicographically).
        Parameters:
        a1 - the first AnnotationMirror to compare
        a2 - the second AnnotationMirror to compare
        Returns:
        true iff a1 and a2 have the same annotation name
        See Also:
        areSame(AnnotationMirror, AnnotationMirror)

      • areSameByName

        @EqualsMethod
public static boolean areSameByName​(javax.lang.model.element.AnnotationMirror a1,
                                    javax.lang.model.element.AnnotationMirror a2)
        Return true iff a1 and a2 have the same annotation type.
        Parameters:
        a1 - the first AnnotationMirror to compare
        a2 - the second AnnotationMirror to compare
        Returns:
        true iff a1 and a2 have the same annotation name
        See Also:
        areSame(AnnotationMirror, AnnotationMirror)

      • areSameByName

        public static boolean areSameByName​(javax.lang.model.element.AnnotationMirror am,
                                    java.lang.String aname)
        Checks that the annotation am has the name aname (a fully-qualified type name). Values are ignored.
        Parameters:
        am - the AnnotationMirror whose name to compare
        aname - the string to compare
        Returns:
        true if aname is the name of am

      • areSame

        public static boolean areSame​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c1,
                              java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c2)
        Checks that two collections contain the same annotations.
        Parameters:
        c1 - the first collection to compare
        c2 - the second collection to compare
        Returns:
        true iff c1 and c2 contain the same annotations, according to areSame(AnnotationMirror, AnnotationMirror)

      • containsSame

        public static boolean containsSame​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                   javax.lang.model.element.AnnotationMirror anno)
        Checks that the collection contains the annotation. Using Collection.contains does not always work, because it does not use areSame for comparison.
        Parameters:
        c - a collection of AnnotationMirrors
        anno - the AnnotationMirror to search for in c
        Returns:
        true iff c contains anno, according to areSame

      • getSame

        public static @Nullable javax.lang.model.element.AnnotationMirror getSame​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                                                          javax.lang.model.element.AnnotationMirror anno)
        Returns the AnnotationMirror in c that is the same annotation as anno.
        Parameters:
        c - a collection of AnnotationMirrors
        anno - the AnnotationMirror to search for in c
        Returns:
        AnnotationMirror with the same class as anno iff c contains anno, according to areSame; otherwise, null

      • containsSameByClass

        public static boolean containsSameByClass​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                          java.lang.Class<? extends java.lang.annotation.Annotation> anno)
        Checks that the collection contains the annotation. Using Collection.contains does not always work, because it does not use areSame for comparison.

        This method is not very efficient. It is more efficient to use AnnotatedTypeFactory#containsSameByClass or containsSameByName(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror>, java.lang.String).

        Parameters:
        c - a collection of AnnotationMirrors
        anno - the annotation class to search for in c
        Returns:
        true iff c contains anno, according to areSameByClass

      • getAnnotationByClass

        public static @Nullable javax.lang.model.element.AnnotationMirror getAnnotationByClass​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                                                                       java.lang.Class<? extends java.lang.annotation.Annotation> anno)
        Returns the AnnotationMirror in c that has the same class as anno.

        This method is not very efficient. It is more efficient to use AnnotatedTypeFactory#getAnnotationByClass or getAnnotationByName(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror>, java.lang.String).

        Parameters:
        c - a collection of AnnotationMirrors
        anno - the class to search for in c
        Returns:
        AnnotationMirror with the same class as anno iff c contains anno, according to areSameByClass; otherwise, null

      • containsSameByName

        public static boolean containsSameByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                         java.lang.String anno)
        Checks that the collection contains an annotation of the given name. Differs from using Collection.contains, which does not use areSameByName for comparison.
        Parameters:
        c - a collection of AnnotationMirrors
        anno - the name to search for in c
        Returns:
        true iff c contains anno, according to areSameByName

      • getAnnotationByName

        public static @Nullable javax.lang.model.element.AnnotationMirror getAnnotationByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                                                                      java.lang.String anno)
        Returns the AnnotationMirror in c that has the same name as anno.
        Parameters:
        c - a collection of AnnotationMirrors
        anno - the name to search for in c
        Returns:
        AnnotationMirror with the same name as anno iff c contains anno, according to areSameByName; otherwise, null

      • containsSameByName

        public static boolean containsSameByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                         javax.lang.model.element.AnnotationMirror anno)
        Checks that the collection contains an annotation of the given name. Differs from using Collection.contains, which does not use areSameByName for comparison.
        Parameters:
        c - a collection of AnnotationMirrors
        anno - the annotation whose name to search for in c
        Returns:
        true iff c contains anno, according to areSameByName

      • getSameByName

        public static @Nullable javax.lang.model.element.AnnotationMirror getSameByName​(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                                                                javax.lang.model.element.AnnotationMirror anno)
        Returns the AnnotationMirror in c that is the same annotation as anno ignoring values.
        Parameters:
        c - a collection of AnnotationMirrors
        anno - the annotation whose name to search for in c
        Returns:
        AnnotationMirror with the same class as anno iff c contains anno, according to areSameByName; otherwise, null

      • compareAnnotationMirrors

        public static int compareAnnotationMirrors​(javax.lang.model.element.AnnotationMirror a1,
                                           javax.lang.model.element.AnnotationMirror a2)
        Provide an ordering for AnnotationMirrors. AnnotationMirrors are first compared by their fully-qualified names, then by their element values in order of the name of the element.
        Parameters:
        a1 - the first annotation
        a2 - the second annotation
        Returns:
        an ordering over AnnotationMirrors based on their name and values

      • hasInheritedMeta

        public static boolean hasInheritedMeta​(javax.lang.model.element.AnnotationMirror anno)
        Returns true if the given annotation has a @Inherited meta-annotation.
        Parameters:
        anno - the annotation to check for an @Inherited meta-annotation
        Returns:
        true if the given annotation has a @Inherited meta-annotation

      • getElementKindsForTarget

        public static java.util.EnumSet<javax.lang.model.element.ElementKind> getElementKindsForTarget​(@Nullable java.lang.annotation.Target target)
        Returns the set of ElementKinds to which target applies, ignoring TYPE_USE.
        Parameters:
        target - a location where an annotation can be written
        Returns:
        the set of ElementKinds to which target applies, ignoring TYPE_USE

      • getElementKindsForElementType

        public static java.util.EnumSet<javax.lang.model.element.ElementKind> getElementKindsForElementType​(java.lang.annotation.ElementType elementType)
        Returns the set of ElementKinds corresponding to elementType. If the element type is TYPE_USE, then ElementKinds returned should be the same as those returned for TYPE and TYPE_PARAMETER, but this method returns the empty set instead.
        Parameters:
        elementType - the elementType to find ElementKinds for
        Returns:
        the set of ElementKinds corresponding to elementType

      • getElementValueOrNull

        public static <T> @Nullable T getElementValueOrNull​(javax.lang.model.element.AnnotationMirror anno,
                                                    java.lang.CharSequence elementName,
                                                    java.lang.Class<T> expectedType,
                                                    boolean useDefaults)
        Get the element with the name elementName of the annotation anno, or return null if no such element exists.

        This method is intended only for use by the framework. A checker implementation should use getElementValue(AnnotationMirror, ExecutableElement, Class, Object).

        Type Parameters:
        T - the class of the type
        Parameters:
        anno - the annotation whose element to access
        elementName - the name of the element to access
        expectedType - the type of the element and the return value
        useDefaults - whether to apply default values to the element
        Returns:
        the value of the element with the given name, or null

      • getElementValueArrayOrNull

        public static <T> @Nullable java.util.List<T> getElementValueArrayOrNull​(javax.lang.model.element.AnnotationMirror anno,
                                                                         java.lang.CharSequence elementName,
                                                                         java.lang.Class<T> expectedType,
                                                                         boolean useDefaults)
        Get the element with the name elementName of the annotation anno, or return null if no such element exists. One element of the result has type expectedType.

        This method is intended only for use by the framework. A checker implementation should use getElementValue(AnnotationMirror, ExecutableElement, Class, Object).

        Type Parameters:
        T - the class of the component type
        Parameters:
        anno - the annotation whose element to access
        elementName - the name of the element to access
        expectedType - the component type of the element and of the return value
        useDefaults - whether to apply default values to the element
        Returns:
        the value of the element with the given name, or null

      • getElementValueArray

        @Deprecated
public static <T> java.util.List<T> getElementValueArray​(javax.lang.model.element.AnnotationMirror anno,
                                                         java.lang.CharSequence elementName,
                                                         java.lang.Class<T> expectedType,
                                                         boolean useDefaults)
        Deprecated.
        use #getElementValueArray(AnnotationMirror, ExecutableElement, Class) or #getElementValueArray(AnnotationMirror, ExecutableElement, Class, Object)
        Get the element with the name elementName of the annotation anno, where the element has an array type. One element of the result has type expectedType.

        Parameter useDefaults is used to determine whether default values should be used for annotation values. Finding defaults requires more computation, so should be false when no defaulting is needed.

        This method is intended only for use by the framework. A checker implementation should use #getElementValueArray(AnnotationMirror, ExecutableElement, Class) or #getElementValueArray(AnnotationMirror, ExecutableElement, Class, Object).

        Type Parameters:
        T - the class of the type
        Parameters:
        anno - the annotation to disassemble
        elementName - the name of the element to access
        expectedType - the component type of the element and of the return type
        useDefaults - whether to apply default values to the element
        Returns:
        the value of the element with the given name; it is a new list, so it is safe for clients to side-effect

      • getElementValueClassName

        @Deprecated
public static @CanonicalName javax.lang.model.element.Name getElementValueClassName​(javax.lang.model.element.AnnotationMirror anno,
                                                                                    java.lang.CharSequence elementName,
                                                                                    boolean useDefaults)
        Deprecated.
        use an ExecutableElement
        Get the Name of the class that is referenced by element elementName.

        This is a convenience method for the most common use-case. It is like getElementValue(anno, elementName, ClassType.class).getQualifiedName(), but this method ensures consistent use of the qualified name.

        This method is intended only for use by the framework. A checker implementation should use anno.getElementValues().get(someElement).getValue().asElement().getQualifiedName();.

        Parameters:
        anno - the annotation to disassemble
        elementName - the name of the element to access; it must be present in the annotation
        useDefaults - whether to apply default values to the element
        Returns:
        the name of the class that is referenced by element with the given name; may be an empty name, for a local or anonymous class

      • getElementValueBoolean

        public static boolean getElementValueBoolean​(javax.lang.model.element.AnnotationMirror anno,
                                             javax.lang.model.element.ExecutableElement element,
                                             boolean defaultValue)
        Get the given boolean element of the annotation anno.
        Parameters:
        anno - the annotation whose element to access
        element - the element to access
        defaultValue - the value to return if the element is not present
        Returns:
        the value of the element with the given name

      • getElementValueInt

        public static int getElementValueInt​(javax.lang.model.element.AnnotationMirror anno,
                                     javax.lang.model.element.ExecutableElement element)
        Get the given integer element of the annotation anno.
        Parameters:
        anno - the annotation whose element to access
        element - the element to access
        Returns:
        the value of the element with the given name

      • getElementValueInt

        public static int getElementValueInt​(javax.lang.model.element.AnnotationMirror anno,
                                     javax.lang.model.element.ExecutableElement element,
                                     int defaultValue)
        Get the given integer element of the annotation anno.
        Parameters:
        anno - the annotation whose element to access
        element - the element to access
        defaultValue - the value to return if the element is not present
        Returns:
        the value of the element with the given name

      • getElementValueLong

        public static long getElementValueLong​(javax.lang.model.element.AnnotationMirror anno,
                                       javax.lang.model.element.ExecutableElement element,
                                       long defaultValue)
        Get the given long element of the annotation anno.
        Parameters:
        anno - the annotation whose element to access
        element - the element to access
        defaultValue - the value to return if the element is not present
        Returns:
        the value of the element with the given name

      • getElementValueEnum

        public static <T extends java.lang.Enum<T>> T getElementValueEnum​(javax.lang.model.element.AnnotationMirror anno,
                                                                  javax.lang.model.element.ExecutableElement element,
                                                                  java.lang.Class<T> expectedType)
        Get the element with the name name of the annotation anno. The result is an enum of type T.
        Type Parameters:
        T - the class of the type
        Parameters:
        anno - the annotation to disassemble
        element - the element to access; it must be present in the annotation
        expectedType - the type of the element and the return value, an enum
        Returns:
        the value of the element with the given name

      • getElementValueEnum

        public static <T extends java.lang.Enum<T>> T getElementValueEnum​(javax.lang.model.element.AnnotationMirror anno,
                                                                  javax.lang.model.element.ExecutableElement element,
                                                                  java.lang.Class<T> expectedType,
                                                                  T defaultValue)
        Get the element with the name name of the annotation anno. The result is an enum of type T.
        Type Parameters:
        T - the class of the type
        Parameters:
        anno - the annotation to disassemble
        element - the element to access
        expectedType - the type of the element and the return value, an enum
        defaultValue - the value to return if the element is not present
        Returns:
        the value of the element with the given name

      • getElementValueEnumArray

        public static <T extends java.lang.Enum<T>> T[] getElementValueEnumArray​(javax.lang.model.element.AnnotationMirror anno,
                                                                         javax.lang.model.element.ExecutableElement element,
                                                                         java.lang.Class<T> expectedType)
        Get the element with the name name of the annotation anno. The result is an array of type T.
        Type Parameters:
        T - the enum class of the component type
        Parameters:
        anno - the annotation to disassemble
        element - the element to access; it must be present in the annotation
        expectedType - the component type of the element and of the return value, an enum
        Returns:
        the value of the element with the given name

      • getElementValueEnumArray

        public static <T extends java.lang.Enum<T>> T[] getElementValueEnumArray​(javax.lang.model.element.AnnotationMirror anno,
                                                                         javax.lang.model.element.ExecutableElement element,
                                                                         java.lang.Class<T> expectedType,
                                                                         T[] defaultValue)
        Get the element with the name name of the annotation anno. The result is an array of type T.
        Type Parameters:
        T - the enum class of the component type
        Parameters:
        anno - the annotation to disassemble
        element - the element to access
        expectedType - the component type of the element and of the return type
        defaultValue - the value to return if the annotation does not have the element
        Returns:
        the value of the element with the given name

      • getElementValueArray

        public static <T> java.util.List<T> getElementValueArray​(javax.lang.model.element.AnnotationMirror anno,
                                                         javax.lang.model.element.ExecutableElement element,
                                                         java.lang.Class<T> expectedType)
        Get the given element of the annotation anno, where the element has an array type. One element of the result has type expectedType.
        Type Parameters:
        T - the class of the component type
        Parameters:
        anno - the annotation to disassemble
        element - the element to access; it must be present in the annotation
        expectedType - the component type of the element and of the return type
        Returns:
        the value of the element with the given name; it is a new list, so it is safe for clients to side-effect

      • getElementValueArray

        public static <T> java.util.List<T> getElementValueArray​(javax.lang.model.element.AnnotationMirror anno,
                                                         javax.lang.model.element.ExecutableElement element,
                                                         java.lang.Class<T> expectedType,
                                                         java.util.List<T> defaultValue)
        Get the given element of the annotation anno, where the element has an array type. One element of the result has type expectedType.
        Type Parameters:
        T - the class of the component type
        Parameters:
        anno - the annotation to disassemble
        element - the element to access
        expectedType - the component type of the element and of the return type
        defaultValue - the value to return if the element is not present
        Returns:
        the value of the element with the given name; it is a new list, so it is safe for clients to side-effect

      • annotationValueListToEnumArray

        public static <T extends java.lang.Enum<T>> T[] annotationValueListToEnumArray​(javax.lang.model.element.AnnotationValue avList,
                                                                               java.lang.Class<T> expectedType)
        Converts a list of AnnotationValue to an array of enum.
        Type Parameters:
        T - the element type of the enum array
        Parameters:
        avList - a list of AnnotationValue
        expectedType - the component type of the element and of the return type, an enum
        Returns:
        an array of enum, converted from the input list

      • annotationValueListToEnumArray

        public static <T extends java.lang.Enum<T>> T[] annotationValueListToEnumArray​(java.util.List<javax.lang.model.element.AnnotationValue> la,
                                                                               java.lang.Class<T> expectedType)
        Converts a list of AnnotationValue to an array of enum.
        Type Parameters:
        T - the element type of the enum array
        Parameters:
        la - a list of AnnotationValue
        expectedType - the component type of the element and of the return type, an enum
        Returns:
        an array of enum, converted from the input list

      • getElementValueClassName

        public static @CanonicalName javax.lang.model.element.Name getElementValueClassName​(javax.lang.model.element.AnnotationMirror anno,
                                                                                    javax.lang.model.element.ExecutableElement element)
        Get the Name of the class that is referenced by element element.

        This is a convenience method for the most common use-case. It is like getElementValue(anno, element, ClassType.class).getQualifiedName(), but this method ensures consistent use of the qualified name.

        This method is intended only for use by the framework. A checker implementation should use anno.getElementValues().get(someElement).getValue().asElement().getQualifiedName();.

        Parameters:
        anno - the annotation to disassemble
        element - the element to access; it must be present in the annotation
        Returns:
        the name of the class that is referenced by element with the given name; may be an empty name, for a local or anonymous class

      • getElementValueClassNames

        public static java.util.List<@CanonicalName javax.lang.model.element.Name> getElementValueClassNames​(javax.lang.model.element.AnnotationMirror anno,
                                                                                                     javax.lang.model.element.ExecutableElement element)
        Get the list of Names of the classes that are referenced by element element. It fails if the class wasn't found.
        Parameters:
        anno - the annotation whose field to access; it must be present in the annotation
        element - the element/field of anno whose content is a list of classes
        Returns:
        the names of classes in anno.annoElement

      • sameElementValues

        @EqualsMethod
public static boolean sameElementValues​(javax.lang.model.element.AnnotationMirror am1,
                                        javax.lang.model.element.AnnotationMirror am2)
        Returns true if the two annotations have the same elements (fields). The arguments am1 and am2 must be the same type of annotation.
        Parameters:
        am1 - the first AnnotationMirror to compare
        am2 - the second AnnotationMirror to compare
        Returns:
        true if the two annotations have the same elements (fields)

      • sameAnnotationValue

        public static boolean sameAnnotationValue​(javax.lang.model.element.AnnotationValue av1,
                                          javax.lang.model.element.AnnotationValue av2)
        Return true iff the two AnnotationValue objects are the same. Use this instead of CheckerFrameworkAnnotationValue.equals, which wouldn't get called if the receiver is some AnnotationValue other than CheckerFrameworkAnnotationValue.
        Parameters:
        av1 - the first AnnotationValue to compare
        av2 - the second AnnotationValue to compare
        Returns:
        true if the two annotation values are the same

      • annotationValueContains

        public static boolean annotationValueContains​(@Nullable javax.lang.model.element.AnnotationValue avList,
                                              java.lang.String s)
        Returns true if an AnnotationValue list contains the given value.

        Using this method is slightly cheaper than creating a new List<String> just for the purpose of testing containment within it.

        Parameters:
        avList - an AnnotationValue that is null or a list of Strings
        s - a string
        Returns:
        true if av contains s

      • annotationValueContains

        public static boolean annotationValueContains​(java.util.List<? extends javax.lang.model.element.AnnotationValue> avList,
                                              java.lang.String s)
        Returns true if an AnnotationValue list contains the given value.

        Using this method is slightly cheaper than creating a new List<String> just for the purpose of testing containment within it.

        Parameters:
        avList - a list of Strings (as AnnotationValues)
        s - a string
        Returns:
        true if av contains s

      • annotationValueContainsToString

        public static boolean annotationValueContainsToString​(@Nullable javax.lang.model.element.AnnotationValue avList,
                                                      java.lang.String s)
        Returns true if an AnnotationValue list contains a value whose toString() is the given string.

        Using this method is slightly cheaper than creating a new List just for the purpose of testing containment within it.

        Parameters:
        avList - an AnnotationValue that is null or a list
        s - a string
        Returns:
        true if av contains s

      • annotationValueContainsToString

        public static boolean annotationValueContainsToString​(java.util.List<? extends javax.lang.model.element.AnnotationValue> avList,
                                                      java.lang.String s)
        Returns true if an AnnotationValue list contains a value whose toString() is the given string.

        Using this method is slightly cheaper than creating a new List just for the purpose of testing containment within it.

        Parameters:
        avList - a list of Strings (as AnnotationValues)
        s - a string
        Returns:
        true if av contains s

      • annotationValueToList

        public static <T> java.util.List<T> annotationValueToList​(javax.lang.model.element.AnnotationValue avList,
                                                          java.lang.Class<T> expectedType)
        Converts an annotation value to a list.

        To test containment, use annotationValueContains(AnnotationValue, String) or annotationValueContainsToString(AnnotationValue, String).

        Type Parameters:
        T - the class of the type
        Parameters:
        avList - an AnnotationValue that is a list of Strings
        expectedType - the component type of the argument and of the return type, an enum
        Returns:
        the annotation value, converted to a list

      • annotationValueToList

        public static <T> java.util.List<T> annotationValueToList​(java.util.List<? extends javax.lang.model.element.AnnotationValue> avList,
                                                          java.lang.Class<T> expectedType)
        Converts an annotation value to a list.

        To test containment, use annotationValueContains(List, String) or annotationValueContainsToString(List, String).

        Type Parameters:
        T - the class of the type
        Parameters:
        avList - a list of Strings (as AnnotationValues)
        expectedType - the component type of the argument and of the return type, an enum
        Returns:
        the annotation value, converted to a list

      • updateMappingToImmutableSet

        public static <T extends @NonNull java.lang.Object> void updateMappingToImmutableSet​(java.util.Map<T,​AnnotationMirrorSet> map,
                                                                                     T key,
                                                                                     AnnotationMirrorSet newQual)
        Update a map, to add newQual to the set that key maps to. The mapped-to element is an unmodifiable set.

        See org.checkerframework.framework.type.QualifierHierarchy#updateMappingToMutableSet(QualifierHierarchy, Map, Object, AnnotationMirror).

        Type Parameters:
        T - the key type
        Parameters:
        map - the map to update
        key - the key whose value to update
        newQual - the element to add to the given key's value

      • getExplicitAnnotationsOnConstructorResult

        public static AnnotationMirrorSet getExplicitAnnotationsOnConstructorResult​(com.sun.source.tree.MethodTree constructorDeclaration)
        Returns the annotations explicitly written on a constructor result. Callers should check that constructorDeclaration is in fact a declaration of a constructor.
        Parameters:
        constructorDeclaration - declaration tree of constructor
        Returns:
        set of annotations explicit on the resulting type of the constructor

      • isDeclarationAnnotation

        public static boolean isDeclarationAnnotation​(javax.lang.model.element.AnnotationMirror anno)
        Returns true if anno is a declaration annotation. In other words, returns true if anno cannot be written on uses of types.
        Parameters:
        anno - the AnnotationMirror
        Returns:
        true if anno is a declaration annotation

      • hasTypeQualifierElementTypes

        public static boolean hasTypeQualifierElementTypes​(java.lang.annotation.ElementType[] elements,
                                                   java.lang.Class<?> cls)
        Returns true if the given array contains ElementType.TYPE_USE, false otherwise.
        Parameters:
        elements - an array of ElementType values
        cls - the annotation class being tested; used for diagnostic messages only
        Returns:
        true iff the give array contains ElementType.TYPE_USE
        Throws:
        java.lang.RuntimeException - if the array contains both ElementType.TYPE_USE and something besides ElementType.TYPE_PARAMETER

      • toStringSimple

        @SideEffectFree
public static java.lang.String toStringSimple​(AnnotationMirrorSet annos)
        Returns a string representation of the annotation mirrors, using simple (not fully-qualified) names.
        Parameters:
        annos - annotations to format
        Returns:
        the string representation, using simple (not fully-qualified) names

      • toStringSimple

        @SideEffectFree
public static java.lang.String toStringSimple​(javax.lang.model.element.AnnotationMirror am)
        Returns a string representation of the annotation mirror, using simple (not fully-qualified) names.
        Parameters:
        am - annotation to format
        Returns:
        the string representation, using simple (not fully-qualified) names

      • toStringSimple

        public static void toStringSimple​(javax.lang.model.element.AnnotationMirror am,
                                  java.lang.StringBuilder sb)
        Appends a string representation of the annotation mirror, using simple (not fully-qualified) names, to the StringBuilder.
        Parameters:
        am - annotation to format
        sb - StringBuilder to which the string representation of am, using simple (not fully-qualified) names, is appended

      • annotationMirrorToClass

        public static java.lang.Class<?> annotationMirrorToClass​(javax.lang.model.element.AnnotationMirror am)
        Converts an AnnotationMirror to a Class. Throws an exception if it is not able to do so.
        Parameters:
        am - an AnnotationMirror
        Returns:
        the Class corresponding to the given AnnotationMirror