checkers.util
Class AnnotationUtils

java.lang.Object
  extended by checkers.util.AnnotationUtils

@DefaultQualifier(value="checkers.nullness.quals.NonNull")
public class AnnotationUtils
extends Object

A utility class for working with annotations.


Nested Class Summary
Modifier and Type Class and Description
static class AnnotationUtils.AnnotationBuilder
          Builds an annotation mirror that may have some values.
 
Method Summary
Modifier and Type Method and Description
static Name annotationName(AnnotationMirror annotation)
           
static Comparator<AnnotationMirror> annotationOrdering()
          provide ordering for AnnotationMirror based on their fully qualified name.
static boolean areSame(AnnotationMirror a1, AnnotationMirror a2)
          Checks if both annotations are the same.
static boolean areSame(Collection<AnnotationMirror> c1, Collection<AnnotationMirror> c2)
          Checks that two collections contain the same annotations.
static boolean areSameIgnoringValues(AnnotationMirror a1, AnnotationMirror a2)
           
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 AnnotationMirrors.
static
<T> T
elementValue(AnnotationMirror anno, CharSequence name, Class<T> expectedType)
           
 Map<TypeElement,Set<DefaultLocation>> findDefaultLocations(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(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.
 AnnotationMirror fromClass(Class<? extends Annotation> clazz)
          Creates an AnnotationMirror given by a particular annotation class.
 AnnotationMirror fromName(CharSequence name)
          Creates an AnnotationMirror given by a particular fully-qualified name.
 AnnotationMirror fromName(String name)
          Creates an AnnotationMirror given by a particular fully-qualified name.
static Map<? extends ExecutableElement,? extends AnnotationValue> getElementValuesWithDefaults(AnnotationMirror ad)
          Returns the values of an annotation's elements, including defaults.
static AnnotationUtils getInstance(ProcessingEnvironment env)
           
static
<R extends Enum<R>>
Set<R>
parseEnumConstantArrayValue(AnnotationMirror ad, String field, Class<R> enumType)
           
static List<String> parseStringArrayValue(AnnotationMirror ad, String field)
           
static String parseStringValue(AnnotationMirror ad, String field)
           
 
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 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 AnnotationMirror fromName(String 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

fromClass

public 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(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(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 ExecutableElement,? extends AnnotationValue> getElementValuesWithDefaults(AnnotationMirror ad)
Returns the values of an annotation's elements, including defaults.

Parameters:
ad - annotation to examine
Returns:
the values of the annotation's elements, including defaults
See Also:
AnnotationMirror.getElementValues()

parseEnumConstantArrayValue

@Nullable
public static <R extends Enum<R>> Set<R> parseEnumConstantArrayValue(AnnotationMirror ad,
                                                                              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

@Nullable
public static String parseStringValue(AnnotationMirror ad,
                                               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

@Nullable
public static List<String> parseStringArrayValue(AnnotationMirror ad,
                                                          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

annotationName

@Nullable
public static final 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(AnnotationMirror a1,
                                            AnnotationMirror a2)
Returns:
true iff a1 and a2 have the same annotation type
See Also:
areSame(AnnotationMirror, AnnotationMirror)

areSame

public static boolean areSame(Collection<AnnotationMirror> c1,
                              Collection<AnnotationMirror> c2)
Checks that two collections contain the same annotations.

Returns:
true iff c1 and c2 contain the same annotations

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

elementValue

public static <T> T elementValue(AnnotationMirror anno,
                                 CharSequence name,
                                 Class<T> expectedType)