org.checkerframework.javacutil

Class AnnotationUtils

java.lang.Object

org.checkerframework.javacutil.AnnotationUtils

public class AnnotationUtils
extends Object

A utility class for working with annotations.

Method Summary

Modifier and Type	Method and Description
static @CanonicalName String	annotationName(AnnotationMirror annotation) Returns the fully-qualified name of an annotation as a String.
static boolean	areSame(AnnotationMirror a1, AnnotationMirror a2) Returns true iff both annotations are of the same type and have the same annotation values.
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 a1, AnnotationMirror a2) Return true iff a1 and a2 have the same annotation type.
static boolean	areSameByName(AnnotationMirror am, String aname) Checks that the annotation am has the name aname (a fully-qualified type name).
static int	compareAnnotationMirrors(AnnotationMirror a1, AnnotationMirror a2) Provide ordering for AnnotationMirrors.
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, AnnotationMirror anno) Checks that the collection contains an annotation of the given name.
static boolean	containsSameByName(Collection<? extends AnnotationMirror> c, String anno) Checks that the collection contains an annotation of the given name.
static <V> Map<AnnotationMirror,V>	createAnnotationMap() Create a map suitable for storing AnnotationMirror as keys.
static NavigableSet<AnnotationMirror>	createAnnotationSet() Constructs a Set for storing AnnotationMirrors.
static NavigableSet<AnnotationMirror>	createAnnotationSet(Collection<AnnotationMirror> annos) Constructs a Set for storing AnnotationMirrors contain all the annotations in annos.
static NavigableSet<AnnotationMirror>	createUnmodifiableAnnotationSet(Collection<AnnotationMirror> annos) Constructs an unmodifiable Set for storing AnnotationMirrors contain all the annotations in annos.
static @Nullable AnnotationMirror	getAnnotationByClass(Collection<? extends AnnotationMirror> c, Class<? extends Annotation> anno) Returns the AnnotationMirror in c that has the same class as anno.
static @Nullable 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 ElementKinds corresponding to elementType.
static EnumSet<ElementKind>	getElementKindsForTarget(@Nullable Target target) Returns the set of ElementKinds to which target applies, ignoring TYPE_USE.
static <T> T	getElementValue(AnnotationMirror anno, CharSequence elementName, Class<T> expectedType, boolean useDefaults) Get the element with the name elementName of the annotation anno.
static <T> List<T>	getElementValueArray(AnnotationMirror anno, CharSequence elementName, Class<T> expectedType, boolean useDefaults) Get the element with the name elementName of the annotation anno, where the element has an array type.
static <T> List<T>	getElementValueArrayOrSingleton(AnnotationMirror anno, CharSequence elementName, Class<T> expectedType, boolean useDefaults) Get the element with the name elementName of the annotation anno.
static @CanonicalName Name	getElementValueClassName(AnnotationMirror anno, CharSequence elementName, boolean useDefaults) Get the Name of the class that is referenced by element elementName.
static List<Name>	getElementValueClassNames(AnnotationMirror anno, CharSequence annoElement, boolean useDefaults) Get the list of Names of the classes that are referenced by element elementName.
static <T extends Enum<T>> T	getElementValueEnum(AnnotationMirror anno, CharSequence elementName, Class<T> expectedType, boolean useDefaults) Get the element with the name name of the annotation anno.
static <T extends Enum<T>> List<T>	getElementValueEnumArray(AnnotationMirror anno, CharSequence elementName, Class<T> expectedType, boolean useDefaults) Get the element with the name elementName of the annotation anno, or the default value if no element is present explicitly, where the element has an array type and the elements are Enums.
static <T> T	getElementValueOrNull(AnnotationMirror anno, CharSequence elementName, 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 Map<? extends ExecutableElement,? extends AnnotationValue>	getElementValuesWithDefaults(AnnotationMirror ad) Returns the values of an annotation's elements, including defaults.
static Set<AnnotationMirror>	getExplicitAnnotationsOnConstructorResult(MethodTree constructorDeclaration) Returns the annotations explicitly written on a constructor result.
static @Nullable AnnotationMirror	getSame(Collection<? extends AnnotationMirror> c, AnnotationMirror anno) Returns the AnnotationMirror in c that is the same annotation as anno.
static @Nullable AnnotationMirror	getSameByName(Collection<? extends AnnotationMirror> c, AnnotationMirror anno) Returns the AnnotationMirror in c that is the same annotation as anno ignoring values.
static boolean	hasElementValue(AnnotationMirror anno, CharSequence elementName) Verify whether the element with the name elementName exists in the annotation anno.
static boolean	hasInheritedMeta(AnnotationMirror anno) Returns true if the given annotation has a @Inherited meta-annotation.
static boolean	hasTypeQualifierElementTypes(ElementType[] elements, Class<?> cls) Returns true if the given array contains ElementType.TYPE_USE, false otherwise.
static boolean	isDeclarationAnnotation(AnnotationMirror anno) Returns true if anno is a declaration 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 String	toStringSimple(Set<AnnotationMirror> annos) Returns a string representation of the annotation mirrors, using simple (not fully-qualified) names.
static <T> void	updateMappingToImmutableSet(Map<T,Set<AnnotationMirror>> map, T key, Set<AnnotationMirror> 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 String annotationName(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

areSame

@EqualsMethod
public static boolean areSame(AnnotationMirror a1,
                                            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

areSameByName

@EqualsMethod
public static boolean areSameByName(AnnotationMirror a1,
                                                  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(AnnotationMirror am,
                                    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

areSameByClass

public static boolean areSameByClass(AnnotationMirror am,
                                     Class<? extends Annotation> annoClass)

Checks that the annotation am has the name of annoClass. Values are ignored.

Parameters:

am - the AnnotationMirror whose class to compare

annoClass - the class to compare

Returns:

true if annoclass is the class of am

areSame

public static boolean areSame(Collection<? extends AnnotationMirror> c1,
                              Collection<? extends 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(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.

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 AnnotationMirror getSame(Collection<? extends AnnotationMirror> c,
                                                 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(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.

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 AnnotationMirror getAnnotationByClass(Collection<? extends AnnotationMirror> c,
                                                              Class<? extends Annotation> anno)

Returns the AnnotationMirror in c that has the same class as anno.

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(Collection<? extends AnnotationMirror> c,
                                         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 AnnotationMirror getAnnotationByName(Collection<? extends AnnotationMirror> c,
                                                             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(Collection<? extends AnnotationMirror> c,
                                         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 AnnotationMirror getSameByName(Collection<? extends AnnotationMirror> c,
                                                       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(AnnotationMirror a1,
                                           AnnotationMirror a2)

Provide 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

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 NavigableSet<AnnotationMirror> createAnnotationSet()

Constructs a Set for storing AnnotationMirrors.

It stores at most once instance of AnnotationMirror of a given type, regardless of the annotation element values.

Returns:

a sorted new set to store AnnotationMirror as element

createAnnotationSet

public static NavigableSet<AnnotationMirror> createAnnotationSet(Collection<AnnotationMirror> annos)

Constructs a Set for storing AnnotationMirrors contain all the annotations in annos.

It stores at most once instance of AnnotationMirror of a given type, regardless of the annotation element values.

Parameters:

annos - a Collection of AnnotationMirrors to put in the created set

Returns:

a sorted new set to store AnnotationMirror as element

createUnmodifiableAnnotationSet

public static NavigableSet<AnnotationMirror> createUnmodifiableAnnotationSet(Collection<AnnotationMirror> annos)

Constructs an unmodifiable Set for storing AnnotationMirrors contain all the annotations in annos.

It stores at most once instance of AnnotationMirror of a given type, regardless of the annotation element values.

Parameters:

annos - a Collection of AnnotationMirrors to put in the created set

Returns:

a sorted, unmodifiable, 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.

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 EnumSet<ElementKind> getElementKindsForTarget(@Nullable 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 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.

Parameters:

elementType - the elementType to find ElementKinds for

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 elements, 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

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

Parameters:

am1 - the first AnnotationMirror to compare

am2 - the second AnnotationMirror to compare

Returns:

true if if the two annotations have the same elements (fields)

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.

Parameters:

av1 - the first AnnotationValue to compare

av2 - the second AnnotationValue to compare

Returns:

true if if the two annotation values are the same

hasElementValue

public static boolean hasElementValue(AnnotationMirror anno,
                                      CharSequence elementName)

Verify whether the element with the name elementName exists in the annotation anno.

Parameters:

anno - the annotation to examine

elementName - the name of the element

Returns:

whether the element exists in anno

getElementValue

public static <T> T getElementValue(AnnotationMirror anno,
                                    CharSequence elementName,
                                    Class<T> expectedType,
                                    boolean useDefaults)

Get the element with the name elementName of the annotation anno. The result is expected to have type expectedType.

For elements of array type, use getElementValueArray instead.

For elements of enum type, use getElementValueEnum instead.

Type Parameters:

T - the class of the expected type

Parameters:

anno - the annotation whose element to access

elementName - the name of the element to access

expectedType - the expected type of the element

useDefaults - whether to apply default values to the element

Returns:

the value of the element with the given name

getElementValueOrNull

public static <T> T getElementValueOrNull(AnnotationMirror anno,
                                          CharSequence elementName,
                                          Class<T> expectedType,
                                          boolean useDefaults)

Get the element with the name elementName of the annotation anno, or return null if no such element exists.

Type Parameters:

T - the class of the expected type

Parameters:

anno - the annotation whose element to access

elementName - the name of the element to access

expectedType - the expected type of the element

useDefaults - whether to apply default values to the element

Returns:

the value of the element with the given name, or null

getElementValueEnum

public static <T extends Enum<T>> T getElementValueEnum(AnnotationMirror anno,
                                                        CharSequence elementName,
                                                        Class<T> expectedType,
                                                        boolean useDefaults)

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 expected type

Parameters:

anno - the annotation to disassemble

elementName - the name of the element to access

expectedType - the expected type used to cast the return type, an enum

useDefaults - whether to apply default values to the element

Returns:

the value of the element with the given name

getElementValueArray

public static <T> List<T> getElementValueArray(AnnotationMirror anno,
                                               CharSequence elementName,
                                               Class<T> expectedType,
                                               boolean useDefaults)

Get the element with the name elementName of the annotation anno, where the element 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.

Type Parameters:

T - the class of the expected type

Parameters:

anno - the annotation to disassemble

elementName - the name of the element to access

expectedType - the expected type used to cast 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

getElementValueArrayOrSingleton

public static <T> List<T> getElementValueArrayOrSingleton(AnnotationMirror anno,
                                                          CharSequence elementName,
                                                          Class<T> expectedType,
                                                          boolean useDefaults)

Get the element with the name elementName of the annotation anno. The element has type expectedType or array of 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.

Type Parameters:

T - the class of the expected type

Parameters:

anno - the annotation to disassemble

elementName - the name of the element to access

expectedType - the expected type used to cast 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

getElementValueEnumArray

public static <T extends Enum<T>> List<T> getElementValueEnumArray(AnnotationMirror anno,
                                                                   CharSequence elementName,
                                                                   Class<T> expectedType,
                                                                   boolean useDefaults)

Get the element with the name elementName of the annotation anno, or the default value if no element is present explicitly, where the element has an array type and the elements are Enums. One element of the result is expected to have type expectedType.

Type Parameters:

T - the class of the expected type

Parameters:

anno - the annotation to disassemble

elementName - the name of the element to access

expectedType - the expected type used to cast the return type

useDefaults - whether to apply default values to the element

Returns:

the value of the element with the given name

getElementValueClassName

public static @CanonicalName Name getElementValueClassName(AnnotationMirror anno,
                                                           CharSequence elementName,
                                                           boolean useDefaults)

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.

Parameters:

anno - the annotation to disassemble

elementName - the name of the element to access

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

getElementValueClassNames

public static List<Name> getElementValueClassNames(AnnotationMirror anno,
                                                   CharSequence annoElement,
                                                   boolean useDefaults)

Get the list of Names of the classes that are referenced by element elementName. It fails if the class wasn't found. Like getElementValueClassNames(javax.lang.model.element.AnnotationMirror, java.lang.CharSequence, boolean), but returns classes rather than names.

Parameters:

anno - the annotation whose field to access

annoElement - the element/field of anno whose content is a list of classes

useDefaults - whether to apply default values to the element

Returns:

the names of classes in anno.annoElement

updateMappingToImmutableSet

public static <T> void updateMappingToImmutableSet(Map<T,Set<AnnotationMirror>> map,
                                                   T key,
                                                   Set<AnnotationMirror> 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 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

isDeclarationAnnotation

public static boolean isDeclarationAnnotation(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(ElementType[] elements,
                                                   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:

RuntimeException - if the array contains both ElementType.TYPE_USE and something besides ElementType.TYPE_PARAMETER

toStringSimple

@SideEffectFree
public static String toStringSimple(Set<AnnotationMirror> 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