RoundEnvironment (Java SE 23 & JDK 23)
Description: declaration: module: java.compiler, package: javax.annotation.processing, interface: RoundEnvironment
Keywords: javax.annotation.processing.RoundEnvironment interface

# Interface RoundEnvironment

public interface RoundEnvironment
An annotation processing tool framework will provide an annotation processor with an object implementing this interface so that the processor can query for information about a round of annotation processing.

Since:
  1.6

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `errorRaised()`
  Returns `true` if an error was raised in the prior round of processing; returns `false` otherwise.
  `Set<? extends Element>`
  `getElementsAnnotatedWith(Class<? extends Annotation> a)`
  Returns the elements annotated with the given annotation interface.
  `Set<? extends Element>`
  `getElementsAnnotatedWith(TypeElement a)`
  Returns the elements annotated with the given annotation interface.
  `default Set<? extends Element>`
  `getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations)`
  Returns the elements annotated with one or more of the given annotation interfaces.
  `default Set<? extends Element>`
  `getElementsAnnotatedWithAny(TypeElement... annotations)`
  Returns the elements annotated with one or more of the given annotation interfaces.
  `Set<? extends Element>`
  `getRootElements()`
  Returns the root elements for annotation processing generated by the prior round.
  `boolean`
  `processingOver()`
  Returns `true` if types generated by this round will not be subject to a subsequent round of annotation processing; returns `false` otherwise.

- ## Method Details

  - ### processingOver

    boolean processingOver()
    Returns `true` if types generated by this round will not be subject to a subsequent round of annotation processing; returns `false` otherwise.
    Returns:
      `true` if types generated by this round will not be subject to a subsequent round of annotation processing; returns `false` otherwise

  - ### errorRaised

    boolean errorRaised()
    Returns `true` if an error was raised in the prior round of processing; returns `false` otherwise.
    Returns:
      `true` if an error was raised in the prior round of processing; returns `false` otherwise

  - ### getRootElements

    Set<? extends Element> getRootElements()
    Returns the root elements for annotation processing generated by the prior round.
    API Note:
      Root elements correspond to the top-level declarations in compilation units (JLS section 7.3). Root elements are most commonly types, but can also be packages or modules.
    Returns:
      the root elements for annotation processing generated by the prior round, or an empty set if there were none

  - ### getElementsAnnotatedWith

    Set<? extends Element> getElementsAnnotatedWith(TypeElement a)
    Returns the elements annotated with the given annotation interface. The annotation may appear directly or be inherited. Only package elements, module elements, and type elements included in this round of annotation processing, or declarations of members, constructors, parameters, type parameters, or record components declared within those, are returned. Included type elements are root types and any member types nested within them. Elements of a package are not considered included simply because a `package-info` file for that package was created. Likewise, elements of a module are not considered included simply because a `module-info` file for that module was created.
    Parameters:
      `a` - annotation interface being requested
    Returns:
      the elements annotated with the given annotation interface, or an empty set if there are none
    Throws:
      `IllegalArgumentException` - if the argument does not represent an annotation interface

  - ### getElementsAnnotatedWithAny

    default Set<? extends Element> getElementsAnnotatedWithAny(TypeElement... annotations)
    Returns the elements annotated with one or more of the given annotation interfaces.
    API Note:
      This method may be useful when processing repeating annotations by looking for an annotation interface and its containing annotation interface at the same time.
    Implementation Requirements:
      The default implementation of this method creates an empty result set, iterates over the annotations in the argument array calling `getElementsAnnotatedWith(TypeElement)` on each annotation and adding those results to the result set. Finally, the contents of the result set are returned as an unmodifiable set.
    Parameters:
      `annotations` - annotation interfaces being requested
    Returns:
      the elements annotated with one or more of the given annotation interfaces, or an empty set if there are none
    Throws:
      `IllegalArgumentException` - if the any elements of the argument set do not represent an annotation interface
    See Java Language Specification:
      9.6.3 Repeatable Annotation Interfaces
    Since:
      9

  - ### getElementsAnnotatedWith

    Set<? extends Element> getElementsAnnotatedWith(Class<? extends Annotation> a)
    Returns the elements annotated with the given annotation interface. The annotation may appear directly or be inherited. Only package elements, module elements, and type elements included in this round of annotation processing, or declarations of members, constructors, parameters, type parameters, or record components declared within those, are returned. Included type elements are root types and any member types nested within them. Elements in a package are not considered included simply because a `package-info` file for that package was created. Likewise, elements of a module are not considered included simply because a `module-info` file for that module was created.

    Note: An implementation of this method typically performs an internal conversion from the runtime reflective representation of an annotation interface as a `Class` object to a different representation used for annotation processing. The set of annotation interfaces present in the runtime context may differ from the set of annotation interfaces present in the context of annotation processing in a particular environmental configuration. If an runtime annotation interface is not present in the annotation processing context, the situation is not treated as an error and no elements are found for that annotation interface.

    Parameters:
      `a` - annotation interface being requested
    Returns:
      the elements annotated with the given annotation interface, or an empty set if there are none
    Throws:
      `IllegalArgumentException` - if the argument does not represent an annotation interface
    See Also:
      - `AnnotatedConstruct.getAnnotation(Class)`
      - `AnnotatedConstruct.getAnnotationsByType(Class)`

  - ### getElementsAnnotatedWithAny

    default Set<? extends Element> getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations)
    Returns the elements annotated with one or more of the given annotation interfaces.

    Note: An implementation of this method typically performs an internal conversion from the runtime reflective representation of an annotation interface as a `Class` object to a different representation used for annotation processing. The set of annotation interfaces present in the runtime context may differ from the set of annotation interfaces present in the context of annotation processing in a particular environmental configuration. If an runtime annotation interface is not present in the annotation processing context, the situation is not treated as an error and no elements are found for that annotation interface.

    API Note:
      This method may be useful when processing repeating annotations by looking for an annotation interface and its containing annotation interface at the same time.
    Implementation Requirements:
      The default implementation of this method creates an empty result set, iterates over the annotations in the argument set calling `getElementsAnnotatedWith(Class)` on each annotation and adding those results to the result set. Finally, the contents of the result set are returned as an unmodifiable set.
    Parameters:
      `annotations` - annotation interfaces being requested
    Returns:
      the elements annotated with one or more of the given annotation interfaces, or an empty set if there are none
    Throws:
      `IllegalArgumentException` - if the any elements of the argument set do not represent an annotation interface
    See Java Language Specification:
      9.6.3 Repeatable Annotation Interfaces
    Since:
      9
    See Also:
      - `AnnotatedConstruct.getAnnotation(Class)`
      - `AnnotatedConstruct.getAnnotationsByType(Class)`