Package 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 Details

    • 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 Details

    • 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 mapping 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 @NonNull 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)