org.checkerframework.javacutil

Class AnnotationBuilder

java.lang.Object

org.checkerframework.javacutil.AnnotationBuilder

public class AnnotationBuilder
extends Object

Builds an annotation mirror that may have some values.

Constructing an AnnotationMirror requires:

1. Constructing the builder with the desired annotation class
2. Setting each value individually using setValue methods
3. Calling build() to get the annotation

Once an annotation is built, no further modification or calls to build can be made. Otherwise, a IllegalStateException is thrown.

All setter methods throw IllegalArgumentException if the specified element is not found, or if the given value is not a subtype of the expected type.

TODO: Doesn't type-check arrays yet

Constructor Summary

Constructors

Constructor and Description
AnnotationBuilder(ProcessingEnvironment env, AnnotationMirror annotation) Create a new AnnotationBuilder that copies the given annotation, including its elements/fields.
AnnotationBuilder(ProcessingEnvironment env, @FullyQualifiedName CharSequence name) Create a new AnnotationBuilder for the given annotation name (with no elements/fields, but they can be added later).
AnnotationBuilder(ProcessingEnvironment env, Class<? extends Annotation> anno) Create a new AnnotationBuilder for the given annotation and environment (with no elements/fields, but they can be added later).

Method Summary

Modifier and Type	Method and Description
AnnotationMirror	build()
void	copyElementValuesFromAnnotation(AnnotationMirror valueHolder, Collection<ExecutableElement> ignorableElements) Copies every element value from the given annotation.
void	copyElementValuesFromAnnotation(AnnotationMirror other, String... ignorableElements) Copies every element value from the given annotation.
void	copyRenameElementValuesFromAnnotation(AnnotationMirror valueHolder, Map<String,String> elementNameRenaming) Copies the specified element values from the given annotation, using the specified renaming map.
static Map<String,AnnotationValue>	elementNamesValues(String elementName, Object elementValue) Creates a mapping between element/field names and values.
ExecutableElement	findElement(CharSequence key)
static AnnotationMirror	fromClass(Elements elements, Class<? extends Annotation> aClass) Creates an AnnotationMirror that uses default values for elements/fields.
static AnnotationMirror	fromClass(Elements elements, Class<? extends Annotation> aClass, Map<String,AnnotationValue> elementNamesValues) Creates an AnnotationMirror given by a particular annotation class and a name-to-value mapping for the elements/fields.
static @Nullable AnnotationMirror	fromName(Elements elements, @FullyQualifiedName CharSequence name) Creates an AnnotationMirror given by a particular fully-qualified name.
static @Nullable AnnotationMirror	fromName(Elements elements, @FullyQualifiedName CharSequence name, Map<String,AnnotationValue> elementNamesValues) Creates an AnnotationMirror given by a particular fully-qualified name and element/field values.
TypeElement	getAnnotationElt() Returns the type element of the annotation that is being built.
AnnotationBuilder	removeElement(CharSequence elementName) Remove the element/field with the given name.
AnnotationBuilder	setValue(CharSequence elementName, AnnotationMirror value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Boolean value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Character value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Class<?> value)
AnnotationBuilder	setValue(CharSequence elementName, Double value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Enum<?> value)
AnnotationBuilder	setValue(CharSequence elementName, Enum<?>[] values)
AnnotationBuilder	setValue(CharSequence elementName, Float value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Integer value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, List<? extends Object> values) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Long value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Object[] values) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, Short value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, String value) Set the element/field with the given name, to the given value.
AnnotationBuilder	setValue(CharSequence elementName, TypeMirror value)
AnnotationBuilder	setValue(CharSequence elementName, VariableElement value)
AnnotationBuilder	setValue(CharSequence elementName, VariableElement[] values)
AnnotationBuilder	setValue(ExecutableElement element, List<? extends Object> values) Set the element to the given value.

Methods inherited from class java.lang.Object

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

Constructor Detail

AnnotationBuilder

public AnnotationBuilder(ProcessingEnvironment env,
                         Class<? extends Annotation> anno)

Create a new AnnotationBuilder for the given annotation and environment (with no elements/fields, but they can be added later).

Parameters:

env - the processing environment

anno - the class of the annotation to build

AnnotationBuilder

public AnnotationBuilder(ProcessingEnvironment env,
                         @FullyQualifiedName CharSequence name)

Create a new AnnotationBuilder for the given annotation name (with no elements/fields, but they can be added later).

Parameters:

env - the processing environment

name - the canonical name of the annotation to build

AnnotationBuilder

public AnnotationBuilder(ProcessingEnvironment env,
                         AnnotationMirror annotation)

Create a new AnnotationBuilder that copies the given annotation, including its elements/fields.

Parameters:

env - the processing environment

annotation - the annotation to copy

Method Detail

getAnnotationElt

public TypeElement getAnnotationElt()

Returns the type element of the annotation that is being built.

Returns:

the type element of the annotation that is being built

elementNamesValues

public static Map<String,AnnotationValue> elementNamesValues(String elementName,
                                                             Object elementValue)

Creates a mapping between element/field names and values.

Parameters:

elementName - the name of an element/field to initialize

elementValue - the initial value for the element/field

Returns:

a mappnig from the element name to the element value

fromClass

public static AnnotationMirror fromClass(Elements elements,
                                         Class<? extends Annotation> aClass)

Creates an AnnotationMirror that uses default values for elements/fields. getElementValues on the result returns default values. If any element does not have a default, this method throws an exception.

Most clients should use fromName(javax.lang.model.util.Elements, java.lang.CharSequence), using a Name created by the compiler. This method is provided as a convenience to create an AnnotationMirror from scratch in a checker's code.

Parameters:

elements - the element utilities to use

aClass - the annotation class

Returns:

an AnnotationMirror of the given type

Throws:

UserError - if the annotation corresponding to the class could not be loaded

fromClass

public static AnnotationMirror fromClass(Elements elements,
                                         Class<? extends Annotation> aClass,
                                         Map<String,AnnotationValue> elementNamesValues)

Creates an AnnotationMirror given by a particular annotation class and a name-to-value mapping for the elements/fields.

For other elements, getElementValues on the result returns default values. If any such element does not have a default, this method throws an exception.

Most clients should use fromName(javax.lang.model.util.Elements, java.lang.CharSequence), using a Name created by the compiler. This method is provided as a convenience to create an AnnotationMirror from scratch in a checker's code.

Parameters:

elements - the element utilities to use

aClass - the annotation class

elementNamesValues - the values for the annotation's elements/fields

Returns:

an AnnotationMirror of the given type

fromName

public static @Nullable AnnotationMirror fromName(Elements elements,
                                                  @FullyQualifiedName CharSequence name)

Creates an AnnotationMirror given by a particular fully-qualified name. getElementValues on the result returns default values. If any element does not have a default, this method throws an exception.

This method returns null if the annotation corresponding to the name could not be loaded.

Parameters:

elements - the element utilities to use

name - the name of the annotation to create

Returns:

an AnnotationMirror of type name or null if the annotation couldn't be loaded

fromName

public static @Nullable AnnotationMirror fromName(Elements elements,
                                                  @FullyQualifiedName CharSequence name,
                                                  Map<String,AnnotationValue> elementNamesValues)

Creates an AnnotationMirror given by a particular fully-qualified name and element/field values. If any element is not specified by the elementValues argument, the default value is used. If any such element does not have a default, this method throws an exception.

This method returns null if the annotation corresponding to the name could not be loaded.

Parameters:

elements - the element utilities to use

name - the name of the annotation to create

elementNamesValues - the values for the annotation's elements/fields

Returns:

an AnnotationMirror of type name or null if the annotation couldn't be loaded

build

public AnnotationMirror build()

copyElementValuesFromAnnotation

public void copyElementValuesFromAnnotation(AnnotationMirror other,
                                            String... ignorableElements)

Copies every element value from the given annotation. If an element in the given annotation doesn't exist in the annotation to be built, an error is raised unless the element is specified in ignorableElements.

Parameters:

other - the annotation that holds the values to be copied; need not be an annotation of the same type of the one being built

ignorableElements - the names of elements of other that can be safely dropped

copyElementValuesFromAnnotation

public void copyElementValuesFromAnnotation(AnnotationMirror valueHolder,
                                            Collection<ExecutableElement> ignorableElements)

Copies every element value from the given annotation. If an element in the given annotation doesn't exist in the annotation to be built, an error is raised unless the element is specified in ignorableElements.

Parameters:

valueHolder - the annotation that holds the values to be copied; must be the same type as the annotation being built

ignorableElements - the elements that can be safely dropped

copyRenameElementValuesFromAnnotation

public void copyRenameElementValuesFromAnnotation(AnnotationMirror valueHolder,
                                                  Map<String,String> elementNameRenaming)

Copies the specified element values from the given annotation, using the specified renaming map. Each value in the map must be an element name in the annotation being built. If an element from the given annotation is not a key in the map, it is ignored.

Parameters:

valueHolder - the annotation that holds the values to be copied

elementNameRenaming - a map from element names in valueHolder to element names of the annotation being built

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  AnnotationMirror value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  List<? extends Object> values)

Set the element/field with the given name, to the given value.

Parameters:

elementName - the element/field name

values - the new value for the element/field

Returns:

this

setValue

public AnnotationBuilder setValue(ExecutableElement element,
                                  List<? extends Object> values)

Set the element to the given value.

Parameters:

element - the element

values - the new value for the element

Returns:

this

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Object[] values)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Boolean value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Character value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Double value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Float value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Integer value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Long value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Short value)

Set the element/field with the given name, to the given value.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  String value)

Set the element/field with the given name, to the given value.

removeElement

public AnnotationBuilder removeElement(CharSequence elementName)

Remove the element/field with the given name. Does not err if no such element/field is present.

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  TypeMirror value)

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Class<?> value)

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Enum<?> value)

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  VariableElement value)

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  Enum<?>[] values)

setValue

public AnnotationBuilder setValue(CharSequence elementName,
                                  VariableElement[] values)

findElement

public ExecutableElement findElement(CharSequence key)