org.checkerframework.javacutil

Class AnnotationUtils

java.lang.Object

org.checkerframework.javacutil.AnnotationUtils

public class AnnotationUtils
extends java.lang.Object

A utility class for working with annotations.

Method Summary

Modifier and Type	Method and Description
static java.lang.String	annotationName(javax.lang.model.element.AnnotationMirror annotation)
static java.util.Comparator<javax.lang.model.element.AnnotationMirror>	annotationOrdering() provide ordering for AnnotationMirror based on their fully qualified name.
static boolean	areSame(@Nullable javax.lang.model.element.AnnotationMirror a1, @Nullable javax.lang.model.element.AnnotationMirror a2) Checks if both annotations are the same.
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	areSameByClass(javax.lang.model.element.AnnotationMirror am, java.lang.Class<? extends java.lang.annotation.Annotation> annoClass) Checks that the annotation am has the name of annoClass.
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	areSameIgnoringValues(@Nullable javax.lang.model.element.AnnotationMirror a1, @Nullable javax.lang.model.element.AnnotationMirror a2)
static void	clear()
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 the annotation.
static boolean	containsSameIgnoringValues(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c, javax.lang.model.element.AnnotationMirror anno) Checks that the collection contains the annotation ignoring values.
static <V> java.util.Map<javax.lang.model.element.AnnotationMirror,V>	createAnnotationMap() Create a map suitable for storing AnnotationMirror as keys.
static java.util.Set<javax.lang.model.element.AnnotationMirror>	createAnnotationSet() Constructs a Set suitable for storing AnnotationMirrors.
static 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 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)
static <T> T	getElementValue(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, java.lang.Class<T> expectedType, boolean useDefaults) Get the attribute with the name name of the annotation anno.
static <T> java.util.List<T>	getElementValueArray(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, java.lang.Class<T> expectedType, boolean useDefaults) Get the attribute with the name name of the annotation anno, where the attribute has an array type.
static java.lang.Class<?>	getElementValueClass(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, boolean useDefaults) Get the Class that is referenced by attribute name.
static javax.lang.model.element.Name	getElementValueClassName(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, boolean useDefaults) Get the Name of the class that is referenced by attribute name.
static java.util.List<javax.lang.model.element.Name>	getElementValueClassNames(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, boolean useDefaults) Get the list of Names of the classes that are referenced by attribute name.
static <T extends java.lang.Enum<T>> T	getElementValueEnum(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, java.lang.Class<T> t, boolean useDefaults) Version that is suitable for Enum elements.
static <T extends java.lang.Enum<T>> java.util.List<T>	getElementValueEnumArray(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name, java.lang.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.
static java.util.Map<? extends javax.lang.model.element.ExecutableElement,? extends javax.lang.model.element.AnnotationValue>	getElementValuesWithDefaults(javax.lang.model.element.AnnotationMirror ad) Returns the values of an annotation's attributes, including defaults.
static java.util.Set<javax.lang.model.element.AnnotationMirror>	getExplicitAnnotationsOnConstructorResult(MethodTree constructorDeclaration) Returns the annotations explicitly written on a constructor result.
static 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 javax.lang.model.element.AnnotationMirror	getSameIgnoringValues(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 <T> boolean	hasElementValue(javax.lang.model.element.AnnotationMirror anno, java.lang.CharSequence name) Verify whether the attribute with the name name exists in the annotation anno.
static boolean	hasInheritedMeta(javax.lang.model.element.AnnotationMirror anno) Returns true if the given annotation has a @Inherited meta-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 <T> void	updateMappingToImmutableSet(java.util.Map<T,java.util.Set<javax.lang.model.element.AnnotationMirror>> map, T key, java.util.Set<javax.lang.model.element.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 java.lang.String annotationName(javax.lang.model.element.AnnotationMirror annotation)

Returns:

the fully-qualified name of an annotation as a String

areSame

public static boolean areSame(@Nullable javax.lang.model.element.AnnotationMirror a1,
                              @Nullable javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror a1,
                                            @Nullable javax.lang.model.element.AnnotationMirror a2)

Returns:

true iff a1 and a2 have the same annotation type

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.

(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(javax.lang.model.element.AnnotationMirror am,
                                     java.lang.Class<? extends java.lang.annotation.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(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.

Returns:

true iff c1 and c2 contain the same annotations

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.

Returns:

true iff c contains anno, according to areSame

getSame

public static 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.

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.

Returns:

true iff c contains anno, according to areSameByClass

getAnnotationByClass

public static 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.

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 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 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.

Returns:

AnnotationMirror with the same name as anno iff c contains anno, according to areSameByName; otherwise, null

containsSameIgnoringValues

public static boolean containsSameIgnoringValues(java.util.Collection<? extends javax.lang.model.element.AnnotationMirror> c,
                                                 javax.lang.model.element.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 javax.lang.model.element.AnnotationMirror getSameIgnoringValues(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.

Returns:

AnnotationMirror with the same class as anno iff c contains anno, according to areSameIgnoringValues; otherwise, null

annotationOrdering

public static java.util.Comparator<javax.lang.model.element.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> java.util.Map<javax.lang.model.element.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 java.util.Set<javax.lang.model.element.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(javax.lang.model.element.AnnotationMirror anno)

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

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.

Returns:

the set of ElementKinds corresponding to elementType

getElementValuesWithDefaults

public static java.util.Map<? extends javax.lang.model.element.ExecutableElement,? extends javax.lang.model.element.AnnotationValue> getElementValuesWithDefaults(javax.lang.model.element.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(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.

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.

hasElementValue

public static <T> boolean hasElementValue(javax.lang.model.element.AnnotationMirror anno,
                                          java.lang.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(javax.lang.model.element.AnnotationMirror anno,
                                    java.lang.CharSequence name,
                                    java.lang.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 java.lang.Enum<T>> T getElementValueEnum(javax.lang.model.element.AnnotationMirror anno,
                                                                  java.lang.CharSequence name,
                                                                  java.lang.Class<T> t,
                                                                  boolean useDefaults)

Version that is suitable for Enum elements.

getElementValueArray

public static <T> java.util.List<T> getElementValueArray(javax.lang.model.element.AnnotationMirror anno,
                                                         java.lang.CharSequence name,
                                                         java.lang.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 java.lang.Enum<T>> java.util.List<T> getElementValueEnumArray(javax.lang.model.element.AnnotationMirror anno,
                                                                                       java.lang.CharSequence name,
                                                                                       java.lang.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 javax.lang.model.element.Name getElementValueClassName(javax.lang.model.element.AnnotationMirror anno,
                                                                     java.lang.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 java.util.List<javax.lang.model.element.Name> getElementValueClassNames(javax.lang.model.element.AnnotationMirror anno,
                                                                                      java.lang.CharSequence name,
                                                                                      boolean useDefaults)

Get the list of Names of the classes that are referenced by attribute name.

getElementValueClass

public static java.lang.Class<?> getElementValueClass(javax.lang.model.element.AnnotationMirror anno,
                                                      java.lang.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(java.util.Map<T,java.util.Set<javax.lang.model.element.AnnotationMirror>> map,
                                                   T key,
                                                   java.util.Set<javax.lang.model.element.AnnotationMirror> newQual)

See checkers.types.QualifierHierarchy#updateMappingToMutableSet(QualifierHierarchy, Map, Object, AnnotationMirror) (Not linked because it is in an independent project.

getExplicitAnnotationsOnConstructorResult

public static java.util.Set<javax.lang.model.element.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