checkers.util

Class AnnotationUtils

@NonNull java.lang.Object

checkers.util.AnnotationUtils

public class AnnotationUtils
extends @NonNull Object

A utility class for working with annotations.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AnnotationUtils.AnnotationBuilder Builds an annotation mirror that may have some values.

Method Summary

Methods

Modifier and Type	Method and Description
static @Nullable Name	annotationName(@Nullable AnnotationMirror annotation)
static Comparator<@Nullable 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<@Nullable AnnotationMirror> c1, Collection<@Nullable AnnotationMirror> c2) Checks that two collections contain the same annotations.
static boolean	areSameIgnoringValues(@Nullable AnnotationMirror a1, @Nullable AnnotationMirror a2)
static boolean	containsSame(Collection<@Nullable AnnotationMirror> c, @Nullable AnnotationMirror anno) Checks that the collection contains the annotation.
static boolean	containsSameIgnoringValues(Collection<@Nullable AnnotationMirror> c, @Nullable AnnotationMirror anno) Checks that the collection contains the annotation ignoring values.
static <V extends @NonNull Object> Map<@Nullable AnnotationMirror,V>	createAnnotationMap() Create a map suitable for storing AnnotationMirror as keys.
static Set<@Nullable AnnotationMirror>	createAnnotationSet() Constructs a Set suitable for storing AnnotationMirrors.
static <T extends @NonNull Object> T	elementValue(@Nullable AnnotationMirror anno, CharSequence name, Class<T> expectedType) Get the attribute with the name name of the annotation anno.
static <T extends @NonNull Object> List<T>	elementValueArray(@Nullable AnnotationMirror anno, CharSequence name) Get the attribute with the name name of the annotation anno, where the attribute has an array type.
static <T extends @NonNull Object> List<T>	elementValueArrayWithDefaults(@Nullable AnnotationMirror anno, CharSequence name) 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.
static @ReadOnly String	elementValueClassName(@Nullable AnnotationMirror anno, CharSequence name) name is an annotation field of type Class, and this gives its name.
static <T extends Enum<T>> List<T>	elementValueEnumArrayWithDefaults(@Nullable AnnotationMirror anno, CharSequence name, Class<T> t) 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 <T extends @NonNull Object> T	elementValueWithDefaults(@Nullable AnnotationMirror anno, CharSequence name, Class<T> expectedType) Get the attribute with the name name of the annotation anno, or the default value if no attribute is present explicitly.
Map<TypeElement,Set<DefaultLocation>>	findDefaultLocations(@Nullable Element elt) Finds default annotations starting at the given element, inspecting the element and its enclosing method and class declarations for DefaultQualifier annotations.
Map<TypeElement,Set<DefaultLocation>>	findDefaultLocations(@Nullable TreePath path) Finds default annotations starting at the leaf of the given tree path by inspecting enclosing variable, method, and class declarations for DefaultQualifier annotations.
@Nullable AnnotationMirror	fromClass(Class<? extends Annotation> clazz) Creates an AnnotationMirror given by a particular annotation class.
@Nullable AnnotationMirror	fromName(CharSequence name) Creates an AnnotationMirror given by a particular fully-qualified name.
@Nullable AnnotationMirror	fromName(@ReadOnly String name) Creates an AnnotationMirror given by a particular fully-qualified name.
static Map<? extends @NonNull ExecutableElement,? extends AnnotationValue>	getElementValuesWithDefaults(@Nullable AnnotationMirror ad) Returns the values of an annotation's elements, including defaults.
static AnnotationUtils	getInstance(ProcessingEnvironment env)
static boolean	hasInheritedMeta(@Nullable AnnotationMirror anno) Returns true if the given annotation has a @Inherited meta-annotation.
static <R extends Enum<R>> @Nullable Set<R>	parseEnumConstantArrayValue(@Nullable AnnotationMirror ad, @ReadOnly String field, Class<R> enumType)
static <@Nullable R extends Enum<@Nullable R>> @Nullable R	parseEnumConstantValue(@Nullable AnnotationMirror ad, @ReadOnly String field, Class<@Nullable R> enumType)
static @Nullable List<@ReadOnly String>	parseStringArrayValue(@Nullable AnnotationMirror ad, @ReadOnly String field)
static @ReadOnly String	parseStringValue(@Nullable AnnotationMirror ad, @ReadOnly String field)
static @Nullable Class<?>	parseTypeValue(@Nullable AnnotationMirror ad, @ReadOnly String field)
static <T extends @NonNull Object> void	updateMappingToImmutableSet(Map<T,Set<@Nullable AnnotationMirror>> map, T key, Set<@Nullable AnnotationMirror> newQual)
static <T extends @NonNull Object> boolean	updateMappingToMutableSet(QualifierHierarchy qualHierarchy, Map<T,Set<@Nullable AnnotationMirror>> map, T key, @Nullable AnnotationMirror newQual) Update a mapping from some key to a set of AnnotationMirrors.

Methods inherited from class java.lang.Object

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

Method Detail

getInstance

public static AnnotationUtils getInstance(ProcessingEnvironment env)

fromName

public @Nullable AnnotationMirror fromName(CharSequence name)

Creates an AnnotationMirror given by a particular fully-qualified name.

Parameters:

name - the name of the annotation to create

Returns:

an AnnotationMirror of type name

fromName

public @Nullable AnnotationMirror fromName(@ReadOnly String name)

Creates an AnnotationMirror given by a particular fully-qualified name. getElementValues on the result returns an empty map.

Parameters:

name - the name of the annotation to create

Returns:

an AnnotationMirror of type name

fromClass

public @Nullable AnnotationMirror fromClass(Class<? extends Annotation> clazz)

Creates an AnnotationMirror given by a particular annotation class.

Parameters:

clazz - the annotation class

Returns:

an AnnotationMirror of type given type

findDefaultLocations

public Map<TypeElement,Set<DefaultLocation>> findDefaultLocations(@Nullable TreePath path)

Finds default annotations starting at the leaf of the given tree path by inspecting enclosing variable, method, and class declarations for DefaultQualifier annotations.

Parameters:

path - the tree path from which to start searching

Returns:

a mapping from annotations (as TypeElements) to the DefaultLocations for those annotations

See Also:

findDefaultLocations(Element)

findDefaultLocations

public Map<TypeElement,Set<DefaultLocation>> findDefaultLocations(@Nullable Element elt)

Finds default annotations starting at the given element, inspecting the element and its enclosing method and class declarations for DefaultQualifier annotations.

Parameters:

elt - the element from which to start searching

Returns:

a mapping from annotations (as TypeElements) to the DefaultLocations for those annotations

See Also:

findDefaultLocations(TreePath)

getElementValuesWithDefaults

public static Map<? extends @NonNull ExecutableElement,? extends AnnotationValue> getElementValuesWithDefaults(@Nullable AnnotationMirror ad)

Returns the values of an annotation's elements, including defaults. TODO: Also see JavacElements.getElementValuesWithDefaults: that version is javac specific, but could/should be replaced with this implementation.

Parameters:

ad - annotation to examine

Returns:

the values of the annotation's elements, including defaults

See Also:

AnnotationMirror.getElementValues()

parseEnumConstantValue

public static <@Nullable R extends Enum<@Nullable R>> @Nullable R parseEnumConstantValue(@Nullable AnnotationMirror ad,
                                                                         @ReadOnly String field,
                                                                         Class<@Nullable R> enumType)

Type Parameters:

R - the enum type

Parameters:

ad - the annotation for which a value will be parsed

field - the name of the field to parse

enumType - the type of the enum

Returns:

the enum constant value of the given field

parseEnumConstantArrayValue

public static <R extends Enum<R>> @Nullable Set<R> parseEnumConstantArrayValue(@Nullable AnnotationMirror ad,
                                                               @ReadOnly String field,
                                                               Class<R> enumType)

Type Parameters:

R - the enum type

Parameters:

ad - the annotation for which a value will be parsed

field - the name of the field to parse

enumType - the type of the enum

Returns:

the enum constant values of the given field

parseStringValue

public static @ReadOnly String parseStringValue(@Nullable AnnotationMirror ad,
                                @ReadOnly String field)

Parameters:

ad - the annotation for which a value will be parsed

field - the name of the field to parse

Returns:

the String value of the given field

parseStringArrayValue

public static @Nullable List<@ReadOnly String> parseStringArrayValue(@Nullable AnnotationMirror ad,
                                                     @ReadOnly String field)

Parameters:

ad - the annotation for which a value will be parsed

field - the name of the field to parse

Returns:

the String values of the given field

parseTypeValue

public static @Nullable Class<?> parseTypeValue(@Nullable AnnotationMirror ad,
                                @ReadOnly String field)

Parameters:

ad - the annotation for which a value will be parsed

field - the name of the field to parse

Returns:

the Class value of the given field

annotationName

public static final @Nullable Name annotationName(@Nullable 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 defers 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)

areSame

public static boolean areSame(Collection<@Nullable AnnotationMirror> c1,
              Collection<@Nullable 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<@Nullable AnnotationMirror> c,
                   @Nullable 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.

containsSameIgnoringValues

public static boolean containsSameIgnoringValues(Collection<@Nullable AnnotationMirror> c,
                                 @Nullable 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.

annotationOrdering

public static Comparator<@Nullable 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 extends @NonNull Object> Map<@Nullable 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<@Nullable 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

elementValue

public static <T extends @NonNull Object> T elementValue(@Nullable AnnotationMirror anno,
                                         CharSequence name,
                                         Class<T> expectedType)

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

Note 1: The method only returns attribute values that are explicitly present on anno. Default values are ignored. If default values should be applied, use elementValueWithDefaults instead.

Note 2: The method does not work well for attributes of an array type (as it would return a list of AnnotationValues). Use elementValueArray instead. instead.

elementValueWithDefaults

public static <T extends @NonNull Object> T elementValueWithDefaults(@Nullable AnnotationMirror anno,
                                                     CharSequence name,
                                                     Class<T> expectedType)

Get the attribute with the name name of the annotation anno, or the default value if no attribute is present explicitly. The result is expected to have type expectedType.

Note: The method does not work well for attributes of an array type (as it would return a list of AnnotationValues). Use elementValueArray instead. instead.

elementValueArray

public static <T extends @NonNull Object> List<T> elementValueArray(@Nullable AnnotationMirror anno,
                                                    CharSequence name)

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.

Note: The method only returns attribute values that are explicitly present on anno. Default values are ignored. If default values should be applied, use elementValueArrayWithDefaults instead.

elementValueArrayWithDefaults

public static <T extends @NonNull Object> List<T> elementValueArrayWithDefaults(@Nullable AnnotationMirror anno,
                                                                CharSequence name)

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. One element of the result is expected to have type expectedType.

elementValueEnumArrayWithDefaults

public static <T extends Enum<T>> List<T> elementValueEnumArrayWithDefaults(@Nullable AnnotationMirror anno,
                                                            CharSequence name,
                                                            Class<T> t)

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.

elementValueClassName

public static @ReadOnly String elementValueClassName(@Nullable AnnotationMirror anno,
                                     CharSequence name)

name is an annotation field of type Class, and this gives its name. Like elementValue(anno, name, Class.class).getCanonicalName() except that elementValue() would return a Type.ClassType that would have to be converted; this does that conversion.

hasInheritedMeta

public static boolean hasInheritedMeta(@Nullable AnnotationMirror anno)

Returns true if the given annotation has a @Inherited meta-annotation.

updateMappingToMutableSet

public static <T extends @NonNull Object> boolean updateMappingToMutableSet(QualifierHierarchy qualHierarchy,
                                                            Map<T,Set<@Nullable AnnotationMirror>> map,
                                                            T key,
                                                            @Nullable AnnotationMirror newQual)

Update a mapping from some key to a set of AnnotationMirrors. If the key already exists in the mapping and the new qualifier is in the same qualifier hierarchy as any of the existing qualifiers, do nothing and return false. If the key already exists in the mapping and the new qualifier is not in the same qualifier hierarchy as any of the existing qualifiers, add the qualifier to the existing set and return true. If the key does not exist in the mapping, add the new qualifier as a singleton set and return true.

Parameters:

map - The mapping to modify.

key - The key to update.

newQual - The value to add.

Returns:

Whether there was a qualifier hierarchy collision.

updateMappingToImmutableSet

public static <T extends @NonNull Object> void updateMappingToImmutableSet(Map<T,Set<@Nullable AnnotationMirror>> map,
                                                           T key,
                                                           Set<@Nullable AnnotationMirror> newQual)

See Also:

updateMappingToMutableSet(QualifierHierarchy, Map, Object, AnnotationMirror)