AnnotationUtils (checker-framework 2.5.4 API)

java.lang.Object
- org.checkerframework.javacutil.AnnotationUtils

public class AnnotationUtils
extends Object

A utility class for working with annotations.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static String`	`annotationName(AnnotationMirror annotation)`
`static Comparator<AnnotationMirror>`	`annotationOrdering()` provide ordering for `AnnotationMirror` based on their fully qualified name.
`static boolean`	`areSame(@Nullable AnnotationMirror a1, @Nullable AnnotationMirror a2)` Checks if both annotations are the same.
`static boolean`	`areSame(Collection<? extends AnnotationMirror> c1, Collection<? extends AnnotationMirror> c2)` Checks that two collections contain the same annotations.
`static boolean`	`areSameByClass(AnnotationMirror am, Class<? extends Annotation> annoClass)` Checks that the annotation `am` has the name of `annoClass`.
`static boolean`	`areSameByName(AnnotationMirror am, String aname)` Checks that the annotation `am` has the name `aname` (a fully-qualified type name).
`static boolean`	`areSameIgnoringValues(@Nullable AnnotationMirror a1, @Nullable AnnotationMirror a2)`
`static void`	`clear()`
`static boolean`	`containsSame(Collection<? extends AnnotationMirror> c, AnnotationMirror anno)` Checks that the collection contains the annotation.
`static boolean`	`containsSameByClass(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno)` Checks that the collection contains the annotation.
`static boolean`	`containsSameByName(Collection<? extends AnnotationMirror> c, String anno)` Checks that the collection contains the annotation.
`static boolean`	`containsSameIgnoringValues(Collection<? extends AnnotationMirror> c, AnnotationMirror anno)` Checks that the collection contains the annotation ignoring values.
`static <V> Map<AnnotationMirror,V>`	`createAnnotationMap()` Create a map suitable for storing `AnnotationMirror` as keys.
`static Set<AnnotationMirror>`	`createAnnotationSet()` Constructs a `Set` suitable for storing `AnnotationMirror`s.
`static AnnotationMirror`	`getAnnotationByClass(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno)` Returns the AnnotationMirror in `c` that has the same class as `anno`.
`static AnnotationMirror`	`getAnnotationByName(Collection<? extends AnnotationMirror> c, String anno)` Returns the AnnotationMirror in `c` that has the same name as `anno`.
`static EnumSet<ElementKind>`	`getElementKindsForElementType(ElementType elementType)` Returns the set of `ElementKind`s corresponding to `elementType`.
`static EnumSet<ElementKind>`	`getElementKindsForTarget(@Nullable Target target)`
`static <T> T`	`getElementValue(AnnotationMirror anno, CharSequence name, Class<T> expectedType, boolean useDefaults)` Get the attribute with the name `name` of the annotation `anno`.
`static <T> List<T>`	`getElementValueArray(AnnotationMirror anno, CharSequence name, Class<T> expectedType, boolean useDefaults)` Get the attribute with the name `name` of the annotation `anno`, where the attribute has an array type.
`static Class<?>`	`getElementValueClass(AnnotationMirror anno, CharSequence name, boolean useDefaults)` Get the Class that is referenced by attribute `name`.
`static Name`	`getElementValueClassName(AnnotationMirror anno, CharSequence name, boolean useDefaults)` Get the Name of the class that is referenced by attribute `name`.
`static List<Name>`	`getElementValueClassNames(AnnotationMirror anno, CharSequence name, boolean useDefaults)` Get the list of Names of the classes that are referenced by attribute `name`.
`static <T extends Enum<T>> T`	`getElementValueEnum(AnnotationMirror anno, CharSequence name, Class<T> t, boolean useDefaults)` Version that is suitable for Enum elements.
`static <T extends Enum<T>> List<T>`	`getElementValueEnumArray(AnnotationMirror anno, CharSequence name, Class<T> t, boolean useDefaults)` Get the attribute with the name `name` of the annotation `anno`, or the default value if no attribute is present explicitly, where the attribute has an array type and the elements are `Enum`s.
`static Map<? extends ExecutableElement,? extends AnnotationValue>`	`getElementValuesWithDefaults(AnnotationMirror ad)` Returns the values of an annotation's attributes, including defaults.
`static Set<AnnotationMirror>`	`getExplicitAnnotationsOnConstructorResult(MethodTree constructorDeclaration)` Returns the annotations explicitly written on a constructor result.
`static AnnotationMirror`	`getSame(Collection<? extends AnnotationMirror> c, AnnotationMirror anno)` Returns the AnnotationMirror in `c` that is the same annotation as `anno`.
`static AnnotationMirror`	`getSameIgnoringValues(Collection<? extends AnnotationMirror> c, AnnotationMirror anno)` Returns the AnnotationMirror in `c` that is the same annotation as `anno` ignoring values.
`static <T> boolean`	`hasElementValue(AnnotationMirror anno, CharSequence name)` Verify whether the attribute with the name `name` exists in the annotation `anno`.
`static boolean`	`hasInheritedMeta(AnnotationMirror anno)` Returns true if the given annotation has a @Inherited meta-annotation.
`static boolean`	`sameAnnotationValue(AnnotationValue av1, AnnotationValue av2)` Return true iff the two AnnotationValue objects are the same.
`static boolean`	`sameElementValues(AnnotationMirror am1, AnnotationMirror am2)` Returns true if the two annotations have the same elements (fields).
`static <T> void`	`updateMappingToImmutableSet(Map<T,Set<AnnotationMirror>> map, T key, Set<AnnotationMirror> newQual)` See checkers.types.QualifierHierarchy#updateMappingToMutableSet(QualifierHierarchy, Map, Object, AnnotationMirror) (Not linked because it is in an independent project.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - clear
```
public static void clear()
```
  - annotationName
```
public static final String annotationName(AnnotationMirror annotation)
```
    Returns:
    
    the fully-qualified name of an annotation as a String
  - areSame
```
public static boolean areSame(@Nullable AnnotationMirror a1,
                              @Nullable AnnotationMirror a2)
```
    Checks if both annotations are the same.
    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).
    
    Returns:
    
    true iff a1 and a2 are the same annotation
  - areSameIgnoringValues
```
public static boolean areSameIgnoringValues(@Nullable AnnotationMirror a1,
                                            @Nullable AnnotationMirror a2)
```
    Returns:
    
    true iff a1 and a2 have the same annotation type
    
    See Also:
    
    areSame(AnnotationMirror, AnnotationMirror)
  - areSameByName
```
public static boolean areSameByName(AnnotationMirror am,
                                    String aname)
```
    Checks that the annotation am has the name aname (a fully-qualified type name). Values are ignored.
    (Use areSameByClass(javax.lang.model.element.AnnotationMirror, java.lang.Class<? extends java.lang.annotation.Annotation>) instead of this method when possible. It is faster.)
  - areSameByClass
```
public static boolean areSameByClass(AnnotationMirror am,
                                     Class<? extends Annotation> annoClass)
```
    Checks that the annotation am has the name of annoClass. Values are ignored.
    (Use this method rather than areSameByName(javax.lang.model.element.AnnotationMirror, java.lang.String) when possible. This method is faster.)
  - areSame
```
public static boolean areSame(Collection<? extends AnnotationMirror> c1,
                              Collection<? extends AnnotationMirror> c2)
```
    Checks that two collections contain the same annotations.
    
    Returns:
    
    true iff c1 and c2 contain the same annotations
  - containsSame
```
public static boolean containsSame(Collection<? extends AnnotationMirror> c,
                                   AnnotationMirror anno)
```
    Checks that the collection contains the annotation. Using Collection.contains does not always work, because it does not use areSame for comparison.
    
    Returns:
    
    true iff c contains anno, according to areSame
  - getSame
```
public static AnnotationMirror getSame(Collection<? extends AnnotationMirror> c,
                                       AnnotationMirror anno)
```
    Returns the AnnotationMirror in c that is the same annotation as anno.
    
    Returns:
    
    AnnotationMirror with the same class as anno iff c contains anno, according to areSame; otherwise, null
  - containsSameByClass
```
public static boolean containsSameByClass(Collection<? extends AnnotationMirror> c,
                                          Class<? extends Annotation> anno)
```
    Checks that the collection contains the annotation. Using Collection.contains does not always work, because it does not use areSame for comparison.
    
    Returns:
    
    true iff c contains anno, according to areSameByClass
  - getAnnotationByClass
```
public static AnnotationMirror getAnnotationByClass(Collection<? extends AnnotationMirror> c,
                                                    Class<? extends Annotation> anno)
```
    Returns the AnnotationMirror in c that has the same class as anno.
    
    Returns:
    
    AnnotationMirror with the same class as anno iff c contains anno, according to areSameByClass; otherwise, null
  - containsSameByName
```
public static boolean containsSameByName(Collection<? extends AnnotationMirror> c,
                                         String anno)
```
    Checks that the collection contains the annotation. Using Collection.contains does not always work, because it does not use areSame for comparison.
    
    Returns:
    
    true iff c contains anno, according to areSameByName
  - getAnnotationByName
```
public static AnnotationMirror getAnnotationByName(Collection<? extends AnnotationMirror> c,
                                                   String anno)
```
    Returns the AnnotationMirror in c that has the same name as anno.
    
    Returns:
    
    AnnotationMirror with the same name as anno iff c contains anno, according to areSameByName; otherwise, null
  - containsSameIgnoringValues
```
public static boolean containsSameIgnoringValues(Collection<? extends AnnotationMirror> c,
                                                 AnnotationMirror anno)
```
    Checks that the collection contains the annotation ignoring values. Using Collection.contains does not always work, because it does not use areSameIgnoringValues for comparison.
    
    Returns:
    
    true iff c contains anno, according to areSameIgnoringValues
  - getSameIgnoringValues
```
public static AnnotationMirror getSameIgnoringValues(Collection<? extends AnnotationMirror> c,
                                                     AnnotationMirror anno)
```
    Returns the AnnotationMirror in c that is the same annotation as anno ignoring values.
    
    Returns:
    
    AnnotationMirror with the same class as anno iff c contains anno, according to areSameIgnoringValues; otherwise, null
  - annotationOrdering
```
public static Comparator<AnnotationMirror> annotationOrdering()
```
    provide ordering for AnnotationMirror based on their fully qualified name. The ordering ignores annotation values when ordering.
    The ordering is meant to be used as TreeSet or TreeMap ordering. A Set should not contain two annotations that only differ in values.
  - createAnnotationMap
```
public static <V> Map<AnnotationMirror,V> createAnnotationMap()
```
    Create a map suitable for storing AnnotationMirror as keys.
    It can store one instance of AnnotationMirror of a given declared type, regardless of the annotation element values.
    
    Type Parameters:
    
    V - the value of the map
    
    Returns:
    
    a new map with AnnotationMirror as key
  - createAnnotationSet
```
public static Set<AnnotationMirror> createAnnotationSet()
```
    Constructs a Set suitable for storing AnnotationMirrors.
    It stores at most once instance of AnnotationMirror of a given type, regardless of the annotation element values.
    
    Returns:
    
    a new set to store AnnotationMirror as element
  - hasInheritedMeta
```
public static boolean hasInheritedMeta(AnnotationMirror anno)
```
    Returns true if the given annotation has a @Inherited meta-annotation.
  - getElementKindsForTarget
```
public static EnumSet<ElementKind> getElementKindsForTarget(@Nullable Target target)
```
    Returns:
    
    the set of ElementKinds to which target applies, ignoring TYPE_USE
  - getElementKindsForElementType
```
public static EnumSet<ElementKind> getElementKindsForElementType(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.
    
    Returns:
    
    the set of ElementKinds corresponding to elementType
  - getElementValuesWithDefaults
```
public static Map<? extends ExecutableElement,? extends AnnotationValue> getElementValuesWithDefaults(AnnotationMirror ad)
```
    Returns the values of an annotation's attributes, including defaults. The method with the same name in JavacElements cannot be used directly, because it includes a cast to Attribute.Compound, which doesn't hold for annotations generated by the Checker Framework.
    
    Parameters:
    
    ad - annotation to examine
    
    Returns:
    
    the values of the annotation's elements, including defaults
    
    See Also:
    
    AnnotationMirror.getElementValues(), JavacElements.getElementValuesWithDefaults(AnnotationMirror)
  - sameElementValues
```
public static boolean sameElementValues(AnnotationMirror am1,
                                        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.
  - sameAnnotationValue
```
public static boolean sameAnnotationValue(AnnotationValue av1,
                                          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.
  - hasElementValue
```
public static <T> boolean hasElementValue(AnnotationMirror anno,
                                          CharSequence name)
```
    Verify whether the attribute with the name name exists in the annotation anno.
    
    Parameters:
    
    anno - the annotation to examine
    
    name - the name of the attribute
    
    Returns:
    
    whether the attribute exists in anno
  - getElementValue
```
public static <T> T getElementValue(AnnotationMirror anno,
                                    CharSequence name,
                                    Class<T> expectedType,
                                    boolean useDefaults)
```
    Get the attribute with the name name of the annotation anno. The result is expected to have type expectedType.
    Note 1: The method does not work well for attributes of an array type (as it would return a list of AnnotationValues). Use getElementValueArray instead.
    Note 2: The method does not work for attributes of an enum type, as the AnnotationValue is a VarSymbol and would be cast to the enum type, which doesn't work. Use getElementValueEnum instead.
    
    Parameters:
    
    anno - the annotation to disassemble
    
    name - the name of the attribute to access
    
    expectedType - the expected type used to cast the return type
    
    useDefaults - whether to apply default values to the attribute
    
    Returns:
    
    the value of the attribute with the given name
  - getElementValueEnum
```
public static <T extends Enum<T>> T getElementValueEnum(AnnotationMirror anno,
                                                        CharSequence name,
                                                        Class<T> t,
                                                        boolean useDefaults)
```
    Version that is suitable for Enum elements.
  - getElementValueArray
```
public static <T> List<T> getElementValueArray(AnnotationMirror anno,
                                               CharSequence name,
                                               Class<T> expectedType,
                                               boolean useDefaults)
```
    Get the attribute with the name name of the annotation anno, where the attribute has an array type. One element of the result is expected to have 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.
    
    Parameters:
    
    anno - the annotation to disassemble
    
    name - the name of the attribute to access
    
    expectedType - the expected type used to cast the return type
    
    useDefaults - whether to apply default values to the attribute
    
    Returns:
    
    the value of the attribute with the given name
  - getElementValueEnumArray
```
public static <T extends Enum<T>> List<T> getElementValueEnumArray(AnnotationMirror anno,
                                                                   CharSequence name,
                                                                   Class<T> t,
                                                                   boolean useDefaults)
```
    Get the attribute with the name name of the annotation anno, or the default value if no attribute is present explicitly, where the attribute has an array type and the elements are Enums. One element of the result is expected to have type expectedType.
  - getElementValueClassName
```
public static Name getElementValueClassName(AnnotationMirror anno,
                                            CharSequence name,
                                            boolean useDefaults)
```
    Get the Name of the class that is referenced by attribute name.
    This is a convenience method for the most common use-case. Like getElementValue(anno, name, ClassType.class).getQualifiedName(), but this method ensures consistent use of the qualified name.
  - getElementValueClassNames
```
public static List<Name> getElementValueClassNames(AnnotationMirror anno,
                                                   CharSequence name,
                                                   boolean useDefaults)
```
    Get the list of Names of the classes that are referenced by attribute name.
  - getElementValueClass
```
public static Class<?> getElementValueClass(AnnotationMirror anno,
                                            CharSequence name,
                                            boolean useDefaults)
```
    Get the Class that is referenced by attribute name. This method uses Class.forName to load the class. It returns null if the class wasn't found.
  - updateMappingToImmutableSet
```
public static <T> void updateMappingToImmutableSet(Map<T,Set<AnnotationMirror>> map,
                                                   T key,
                                                   Set<AnnotationMirror> newQual)
```
    See checkers.types.QualifierHierarchy#updateMappingToMutableSet(QualifierHierarchy, Map, Object, AnnotationMirror) (Not linked because it is in an independent project.
  - getExplicitAnnotationsOnConstructorResult
```
public static Set<AnnotationMirror> getExplicitAnnotationsOnConstructorResult(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

Class AnnotationUtils

Method Summary

Methods inherited from class java.lang.Object

Method Detail

clear

annotationName

areSame

areSameIgnoringValues

areSameByName

areSameByClass

areSame

containsSame

getSame

containsSameByClass

getAnnotationByClass

containsSameByName

getAnnotationByName

containsSameIgnoringValues

getSameIgnoringValues

annotationOrdering

createAnnotationMap

createAnnotationSet

hasInheritedMeta

getElementKindsForTarget

getElementKindsForElementType

getElementValuesWithDefaults

sameElementValues

sameAnnotationValue

hasElementValue

getElementValue

getElementValueEnum

getElementValueArray

getElementValueEnumArray

getElementValueClassName

getElementValueClassNames

getElementValueClass

updateMappingToImmutableSet

getExplicitAnnotationsOnConstructorResult