AnnotationBuilder (checker-framework 3.4.0 API)

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

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`AnnotationMirror`	`build()`
`void`	`copyElementValuesFromAnnotation(AnnotationMirror valueHolder, 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.
`ExecutableElement`	`findElement(CharSequence key)`
`static AnnotationMirror`	`fromClass(Elements elements, Class<? extends Annotation> aClass)` Creates an `AnnotationMirror` given by a particular annotation class.
`static @Nullable AnnotationMirror`	`fromName(Elements elements, CharSequence name)` Creates an `AnnotationMirror` given by a particular fully-qualified name.
`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)`

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,
                         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 fully-qualified 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

fromClass
```
public static AnnotationMirror fromClass(Elements elements,
                                         Class<? extends Annotation> aClass)
```
Creates an AnnotationMirror given by a particular annotation class. getElementValues on the result returns an empty map. This may be in conflict with the annotation's definition, which might contain elements (annotation fields). Use an AnnotationBuilder for annotations that contain elements.
This method raises an user error if the annotation corresponding to the class could not be loaded.
Clients can use fromName(javax.lang.model.util.Elements, java.lang.CharSequence) and check the result for null manually, if the error from this method is not desired. 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

fromName
```
public static @Nullable AnnotationMirror fromName(Elements elements,
                                                  CharSequence name)
```
Creates an AnnotationMirror given by a particular fully-qualified name. getElementValues on the result returns an empty map. This may be in conflict with the annotation's definition, which might contain elements (annotation fields). Use an AnnotationBuilder for annotations that contain elements.
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

build
```
public AnnotationMirror build()
```

copyElementValuesFromAnnotation
```
public void copyElementValuesFromAnnotation(AnnotationMirror valueHolder,
                                            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:

valueHolder - the annotation that holds the values to be copied

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