Package org.checkerframework.javacutil

Class AnnotationBuilder

  • public class AnnotationBuilder
extends java.lang.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 Description
      AnnotationBuilder​(javax.annotation.processing.ProcessingEnvironment env, @FullyQualifiedName java.lang.CharSequence name)
      Create a new AnnotationBuilder for the given annotation name (with no elements/fields, but they can be added later).
      AnnotationBuilder​(javax.annotation.processing.ProcessingEnvironment env, java.lang.Class<? extends java.lang.annotation.Annotation> anno)
      Create a new AnnotationBuilder for the given annotation and environment (with no elements/fields, but they can be added later).
      AnnotationBuilder​(javax.annotation.processing.ProcessingEnvironment env, javax.lang.model.element.AnnotationMirror annotation)
      Create a new AnnotationBuilder that copies the given annotation, including its elements/fields.

    • Method Summary

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

      • copyElementValuesFromAnnotation

        public void copyElementValuesFromAnnotation​(javax.lang.model.element.AnnotationMirror other,
                                            java.lang.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​(javax.lang.model.element.AnnotationMirror valueHolder,
                                            java.util.Collection<javax.lang.model.element.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​(javax.lang.model.element.AnnotationMirror valueHolder,
                                                  java.util.Map<java.lang.String,​java.lang.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​(java.lang.CharSequence elementName,
                                  javax.lang.model.element.AnnotationMirror value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.util.List<? extends java.lang.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​(javax.lang.model.element.ExecutableElement element,
                                  java.util.List<? extends @NonNull java.lang.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​(java.lang.CharSequence elementName,
                                  java.lang.Object[] values)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Boolean value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Character value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Double value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Float value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Integer value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Long value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Short value)
        Set the element/field with the given name, to the given value.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.String value)
        Set the element/field with the given name, to the given value.

      • removeElement

        public AnnotationBuilder removeElement​(java.lang.CharSequence elementName)
        Remove the element/field with the given name. Does not err if no such element/field is present.

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  javax.lang.model.type.TypeMirror value)

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Class<?> value)

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Enum<?> value)

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  javax.lang.model.element.VariableElement value)

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  java.lang.Enum<?>[] values)

      • setValue

        public AnnotationBuilder setValue​(java.lang.CharSequence elementName,
                                  javax.lang.model.element.VariableElement[] values)

      • findElement

        public javax.lang.model.element.ExecutableElement findElement​(java.lang.CharSequence key)