Interface VisitorContext

All Superinterfaces:
ClassWriterOutputVisitor, ConversionServiceProvider, ConvertibleValues<Object>, Iterable<Map.Entry<String,Object>>, MutableConvertibleValues<Object>, ValueResolver<CharSequence>
All Known Subinterfaces:
BeanElementVisitorContext
All Known Implementing Classes:
GroovyVisitorContext, JavaVisitorContext, PythonVisitorContext
public interface VisitorContext extends MutableConvertibleValues<Object>, ClassWriterOutputVisitor
Provides a way for TypeElementVisitor classes to log messages during compilation and fail compilation.
Since:
1.0
Author:
James Kleeh, Graeme Rocher

  • Field Details

  • Method Details

    • getLanguage

      VisitorContext.Language getLanguage()
      Returns:
      The visitor context's language.
      Since:
      4.2.0

    • getElementFactory

      ElementFactory<?,?,?,?> getElementFactory()
      Gets the element factory for this visitor context.
      Returns:
      The element factory
      Since:
      2.3.0

    • getElementAnnotationMetadataFactory

      ElementAnnotationMetadataFactory getElementAnnotationMetadataFactory()
      Gets the element annotation metadata factory.
      Returns:
      The element annotation metadata factory
      Since:
      4.0.0

    • getExpressionCompilationContextFactory

      ExpressionCompilationContextFactory getExpressionCompilationContextFactory()
      Returns:
      The expression compilation context factory.
      Since:
      4.0.0

    • getAnnotationMetadataBuilder

      @Internal AbstractAnnotationMetadataBuilder<?,?> getAnnotationMetadataBuilder()
      Gets the annotation metadata builder.
      Returns:
      The annotation metadata builder
      Since:
      4.0.0

    • getAnnotationDefaultValues

      default Map<CharSequence, Object> getAnnotationDefaultValues(String annotationName)
      Resolves the default values declared by the given annotation type.

      Every member that declares a default is reported, whatever the shape of the default: a constant, an enum constant (reported as the constant's name), a class literal (reported as an AnnotationClassValue), an array (including the empty array), a nested annotation (reported as an AnnotationValue) and the empty string. Java, Kotlin and Groovy report the same defaults for the equivalent annotation.

      Python reports the same defaults for a decorator declared as an annotation, with two differences its model forces. A decorator member cannot declare another decorator application as its default, so there is no nested annotation default. And a class reference or list default is only reported as an AnnotationClassValue or an array once the generated Java annotation type exists; until then, while the Python class that declares the decorator is visited, it is reported as the class name or a List. A default expression the Python processor cannot read declares no default.

      This is deliberately more complete than the defaults carried by the written annotation metadata and read back through AnnotationValue.getDefaultValues(), which omits empty string defaults to keep the generated metadata small. Use this method when "no default" has to be told apart from "the default is the empty string" — for instance when comparing two annotations member by member.

      Under KSP the defaults of an annotation type are only resolvable when the annotation is used at least once in the compilation round, because KSP models member defaults on the annotation usage rather than on the annotation class declaration. An unused annotation type reports no defaults.

      Parameters:
      annotationName - The annotation type name
      Returns:
      The default values, or an empty map if the annotation type cannot be resolved
      Since:
      5.1.0

    • getAnnotationRetentionPolicy

      default RetentionPolicy getAnnotationRetentionPolicy(String annotationName)
      Resolves the retention policy declared by the given annotation type.
      Parameters:
      annotationName - The annotation type name
      Returns:
      The retention policy, or RetentionPolicy.RUNTIME if the annotation type cannot be resolved
      Since:
      5.1.0

    • info

      void info(String message, @Nullable Element element)
      Allows printing informational messages.
      Parameters:
      message - The message
      element - The element

    • info

      void info(String message)
      Allows printing informational messages.
      Parameters:
      message - The message

    • fail

      void fail(String message, @Nullable Element element)
      Allows failing compilation for a given element with the given message.
      Parameters:
      message - The message
      element - The element

    • warn

      void warn(String message, @Nullable Element element)
      Allows printing a warning for the given message and element.
      Parameters:
      message - The message
      element - The element

    • getConfiguration

      default VisitorConfiguration getConfiguration()
      Returns:
      The visitor configuration

    • visitMetaInfFile

      Optional<GeneratedFile> visitMetaInfFile(String path, Element... originatingElements)
      Visit a file within the META-INF directory.
      Specified by:
      visitMetaInfFile in interface ClassWriterOutputVisitor
      Parameters:
      path - The path to the file
      originatingElements - The originating elements
      Returns:
      An optional file it was possible to create it

    • visitGeneratedFile

      Optional<GeneratedFile> visitGeneratedFile(String path)
      Visit a file that will be located within the generated source directory.
      Specified by:
      visitGeneratedFile in interface ClassWriterOutputVisitor
      Parameters:
      path - The path to the file
      Returns:
      An optional file it was possible to create it

    • getClasspathResources

      default Iterable<URL> getClasspathResources(String path)
      Obtain a set of resources from the user classpath.
      Parameters:
      path - The path
      Returns:
      An iterable of resources

    • getProjectDir

      default Optional<Path> getProjectDir()
      Obtain the project directory.
      Returns:
      An optional wrapping the project directory

    • getClassesOutputPath

      default Optional<Path> getClassesOutputPath()
      Provide the Path to the annotation processing classes output directory, i.e. the parent of META-INF.

      This might, for example, be used as a convenience for TypeElementVisitor classes to provide relative path strings to addGeneratedResource(String)

      Path resource = ... // absolute path to the resource
visitorContext.getClassesOutputPath().ifPresent(path ->
    visitorContext.addGeneratedResource(path.relativize(resource).toString()));
      Returns:
      Path pointing to the classes output directory

    • getClassElement

      default Optional<ClassElement> getClassElement(String name)
      This method will look up another class element by name. If it cannot be found an empty optional will be returned.
      Parameters:
      name - The name
      Returns:
      The class element

    • getClassElement

      default Optional<ClassElement> getClassElement(String name, ElementAnnotationMetadataFactory annotationMetadataFactory)
      This method will look up another class element by name. If it cannot be found an empty optional will be returned.
      Parameters:
      name - The name
      annotationMetadataFactory - The element annotation metadata factory
      Returns:
      The class element
      Since:
      4.0.0

    • getRequiredClassElement

      default ClassElement getRequiredClassElement(String name, ElementAnnotationMetadataFactory annotationMetadataFactory)
      This method will look up another class element by name. If it cannot be found an exception thrown.
      Parameters:
      name - The name
      annotationMetadataFactory - The element annotation metadata factory
      Returns:
      The class element
      Since:
      4.0.0

    • getClassElement

      default Optional<ClassElement> getClassElement(Class<?> type)
      This method will look up another class element by name. If it cannot be found an empty optional will be returned.
      Parameters:
      type - The name
      Returns:
      The class element

    • getBeanDefinitionInjectionPointResolver

      default BeanDefinitionInjectionPointResolver getBeanDefinitionInjectionPointResolver()
      Returns the resolver for language-specific injection point shapes.
      Returns:
      The injection point resolver
      Since:
      5.2.0

    • getClassElements

      default ClassElement[] getClassElements(String aPackage, String... stereotypes)
      Find all the classes within the given package and having the given annotation.
      Parameters:
      aPackage - The package
      stereotypes - The stereotypes
      Returns:
      The class elements

    • getClassElements

      default List<ClassElement> getClassElements(PackageElement packageElement)
      Find all the classes within the given package.
      Parameters:
      packageElement - The package
      Returns:
      The class elements

    • getOptions

      default Map<String,String> getOptions()
      The annotation processor environment custom options.

      All options names MUST start with MICRONAUT_BASE_OPTION_NAME

      Returns:
      A Map with annotation processor runtime options
      See Also:

    • getGeneratedResources

      @Deprecated(forRemoval=true, since="4.10") default Collection<String> getGeneratedResources()
      Deprecated, for removal: This API element is subject to removal in a future version.
      No longer used
      Provide a collection of generated classpath resources that other TypeElement visitors might want to consume. The generated resources are intended to be strings paths relative to the classpath root.
      Returns:
      a possibly empty collection of resource paths

    • addGeneratedResource

      @Deprecated(forRemoval=true, since="4.10") default void addGeneratedResource(String resource)
      Deprecated, for removal: This API element is subject to removal in a future version.
      No longer used
      Some TypeElementVisitors generate classpath resources that other visitors might be interested in. The generated resources are intended to be strings paths relative to the classpath root
      Parameters:
      resource - the relative path to add