java.lang.Object

org.tquadrat.foundation.ap.APBase

All Implemented Interfaces:: Messager, ProcessingEnvironment, Processor, APHelper

@ClassVersion(sourceVersion="$Id: APBase.java 1061 2023-09-25 16:32:43Z tquadrat $") @API(status=STABLE, since="0.1.0") public abstract class APBase extends Object implements Processor, APHelper

The abstract base class for annotation processors for the Foundation Library.

Author:: Thomas Thrien (thomas.thrien@tquadrat.org)
Version:: $Id: APBase.java 1061 2023-09-25 16:32:43Z tquadrat $
Since:: 0.1.0
UML Diagram: ⁠
UML Diagram for "org.tquadrat.foundation.ap.APBase"
⁠

Field Summary

Fields

Modifier and Type

Field

Description

static final String

ADD_DEBUG_OUTPUT

The name of the annotation processor option that enables the emission of some debug information into the generated code: "org.tquadrat.foundation.ap.addDebugOutput".

private boolean

m_AddDebugOutput

The flag that indicates whether some debug information should be emitted to the generated code.

private Elements

m_ElementUtils

The implementation of some utility methods for operating on elements.

private ProcessingEnvironment

m_Environment

The processing environment.

private Filer

m_Filer

The filer that is used to create new source, class, or auxiliary files.

private boolean

m_IsMavenActive

A flag that indicates whether Maven is active.

private Messager

m_Messager

The Messager that is used to report errors, warnings, and other notices.

private Map<String,String>

m_Options

The options for this annotation processor.

private Types

m_TypeUtils

The implementation of some utility methods for operating on types.

static final String

MAVEN_GOAL

The name of the annotation processor option for the currently active Maven goal: "org.tquadrat.foundation.ap.maven.goal".

static final String

MSG_AnnotationOnlyForFields

Message: "%s: Only fields may be annotated with \'%s\'".

static final String

MSG_FieldsOnly

Message: "Only allowed for fields".

static final String

MSG_IllegalAnnotationUse

The message that indicates the illegal use of an annotation: "%s: Illegal use of annotation \'%s\'".

static final String

MSG_MultipleElements

The message that indicates that more than one element is annotated with the given annotation: "%1$s: Multiple elements are annotated with \'%2$s\'".

static final String

MSG_MultipleFields

The message that indicates that more than one field is annotated with the given annotation: "%1$s: Multiple fields are annotated with \'%2$s\'".

static final String

MSG_StringConstantRequired

The message that indicates that a String constant is required: "\'%s\' needs to be a String constant".

static final String

PACKAGE_NAME

The name for sub-package that holds the generated configuration bean classes: "generated".
Constructor Summary

Constructors

Modifier

Constructor

Description

protected

APBase()

Creates a new APBase instance.
Method Summary

Modifier and Type

Method

Description

final boolean

addDebugOutput()

Returns the flag that indicates whether some debug information should be emitted to the generated code.

private final String

composeMessage(CharSequence msg)

Adds the name of the annotation processor to the given message.

final Iterable<? extends Completion>

getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText)

final Elements

getElementUtils()

final Filer

getFiler()

final Locale

getLocale()

final Messager

getMessager()

protected final Optional<String>

getOption(String option)

Retrieves the option with the given name from the annotation processors startup options.

final Map<String,String>

getOptions()

final SourceVersion

getSourceVersion()

protected abstract Collection<Class<? extends Annotation>>

getSupportedAnnotationClasses()

Returns the classes for the supported annotations.

final Set<String>

getSupportedAnnotationTypes()

final Set<String>

getSupportedOptions()

final SourceVersion

getSupportedSourceVersion()

final Types

getTypeUtils()

final void

init(ProcessingEnvironment processingEnv)

final boolean

isEnumType(TypeMirror type)

Determines whether the given instance of TypeMirror is for an Enum type.

final void

printMessage(Diagnostic.Kind kind, CharSequence msg)

final void

printMessage(Diagnostic.Kind kind, CharSequence msg, Element element)

final void

printMessage(Diagnostic.Kind kind, CharSequence msg, Element element, AnnotationMirror annotation)

final void

printMessage(Diagnostic.Kind kind, CharSequence msg, Element element, AnnotationMirror annotation, AnnotationValue value)

abstract boolean

process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnvironment)

protected final Optional<VariableElement>

retrieveAnnotatedField(RoundEnvironment roundEnvironment, Class<? extends Annotation> annotationClass)

Retrieves the field that is annotated with the given annotation.

final List<Name>

retrieveArgumentNames(ExecutableElement method)

Retrieves the names of a method's arguments.

List<TypeMirror>

retrieveGenericTypes(TypeMirror type)

Retrieves the generic types for the given type.

final void

retrieveInterfaces(TypeElement typeElement, Set<? super TypeElement> interfaces)

Retrieves the interfaces are that implemented or extended by the given type element.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.tquadrat.foundation.ap.APHelper
getAnnotationMirror, getAnnotationValue, getAnnotationValue, getTypeMirrorFromAnnotationValue, getTypeMirrorFromAnnotationValue, hasAnnotation

Methods inherited from interface javax.annotation.processing.Messager
printError, printError, printNote, printNote, printWarning, printWarning

Methods inherited from interface javax.annotation.processing.ProcessingEnvironment
isPreviewEnabled

Field Details
- PACKAGE_NAME
  
  public static final String PACKAGE_NAME
  
  The name for sub-package that holds the generated configuration bean classes: "generated".
  See Also:
  
  Constant Field Values
- ADD_DEBUG_OUTPUT
  
  public static final String ADD_DEBUG_OUTPUT
  
  The name of the annotation processor option that enables the emission of some debug information into the generated code: "org.tquadrat.foundation.ap.addDebugOutput".
  See Also:
  
  Constant Field Values
- MAVEN_GOAL
  
  public static final String MAVEN_GOAL
  
  The name of the annotation processor option for the currently active Maven goal: "org.tquadrat.foundation.ap.maven.goal".
  See Also:
  
  Constant Field Values
- MSG_AnnotationOnlyForFields
  
  public static final String MSG_AnnotationOnlyForFields
  
  Message: "%s: Only fields may be annotated with \'%s\'".
  See Also:
  
  Constant Field Values
- MSG_FieldsOnly
  
  public static final String MSG_FieldsOnly
  
  Message: "Only allowed for fields".
  See Also:
  
  Constant Field Values
- MSG_IllegalAnnotationUse
  
  public static final String MSG_IllegalAnnotationUse
  
  The message that indicates the illegal use of an annotation: "%s: Illegal use of annotation \'%s\'".
  See Also:
  
  Constant Field Values
- MSG_MultipleElements
  
  public static final String MSG_MultipleElements
  
  The message that indicates that more than one element is annotated with the given annotation: "%1$s: Multiple elements are annotated with \'%2$s\'".
  See Also:
  
  Constant Field Values
- MSG_MultipleFields
  
  public static final String MSG_MultipleFields
  
  The message that indicates that more than one field is annotated with the given annotation: "%1$s: Multiple fields are annotated with \'%2$s\'".
  See Also:
  
  Constant Field Values
- MSG_StringConstantRequired
  
  public static final String MSG_StringConstantRequired
  
  The message that indicates that a String constant is required: "\'%s\' needs to be a String constant".
  See Also:
  
  Constant Field Values
- m_AddDebugOutput
  
  private boolean m_AddDebugOutput
  
  The flag that indicates whether some debug information should be emitted to the generated code.
- m_ElementUtils
  
  private Elements m_ElementUtils
  
  The implementation of some utility methods for operating on elements.
- m_Environment
  
  private ProcessingEnvironment m_Environment
  
  The processing environment.
- m_Filer
  
  private Filer m_Filer
  
  The filer that is used to create new source, class, or auxiliary files.
- m_IsMavenActive
  
  private boolean m_IsMavenActive
  
  A flag that indicates whether Maven is active. This is guessed by the existence of the option "org.tquadrat.foundation.ap.maven.goal".
- m_Messager
  
  private Messager m_Messager
  
  The Messager that is used to report errors, warnings, and other notices.
- m_Options
  
  private Map<String,String> m_Options
  
  The options for this annotation processor.
- m_TypeUtils
  
  private Types m_TypeUtils
  
  The implementation of some utility methods for operating on types.
Constructor Details
- APBase
  
  protected APBase()
  
  Creates a new APBase instance.
Method Details
- addDebugOutput
  
  public final boolean addDebugOutput()
  
  Returns the flag that indicates whether some debug information should be emitted to the generated code.
  
  The value is controlled by the value of the annotation processor option "org.tquadrat.foundation.ap.addDebugOutput".
  
  Specified by:
  
  addDebugOutput in interface APHelper
  
  Returns:
  
  true if the debug information should be added, false if not.
- composeMessage
  
  private final String composeMessage(CharSequence msg)
  
  Adds the name of the annotation processor to the given message.
  
  Parameters:
  
  msg - The raw message.
  
  Returns:
  
  The enhanced message.
- getCompletions
  
  public final Iterable<? extends Completion> getCompletions(Element element, AnnotationMirror annotation, ExecutableElement member, String userText)
  
  Specified by:
  
  getCompletions in interface Processor
- getElementUtils
  
  public final Elements getElementUtils()
  
  Specified by:
  
  getElementUtils in interface ProcessingEnvironment
- getFiler
  
  public final Filer getFiler()
  
  Specified by:
  
  getFiler in interface ProcessingEnvironment
- getLocale
  
  public final Locale getLocale()
  
  Specified by:
  
  getLocale in interface ProcessingEnvironment
- getMessager
  
  public final Messager getMessager()
  
  Specified by:
  
  getMessager in interface ProcessingEnvironment
- getOption
  
  protected final Optional<String> getOption(String option)
  
  Retrieves the option with the given name from the annotation processors startup options.
  
  Parameters:
  
  option - The name of the option.
  
  Returns:
  
  An instance of Optional that holds the option value.
- getOptions
  
  public final Map<String,String> getOptions()
  
  Specified by:
  
  getOptions in interface ProcessingEnvironment
- getSourceVersion
  
  public final SourceVersion getSourceVersion()
  
  Specified by:
  
  getSourceVersion in interface ProcessingEnvironment
- getSupportedAnnotationClasses
  
  protected abstract Collection<Class<? extends Annotation>> getSupportedAnnotationClasses()
  
  Returns the classes for the supported annotations.
  
  Returns:
  
  The supported annotations.
- getSupportedAnnotationTypes
  
  public final Set<String> getSupportedAnnotationTypes()
  
  Specified by:
  
  getSupportedAnnotationTypes in interface Processor
- getSupportedOptions
  
  public final Set<String> getSupportedOptions()
  
  Specified by:
  
  getSupportedOptions in interface Processor
- getSupportedSourceVersion
  
  public final SourceVersion getSupportedSourceVersion()
  
  Specified by:
  
  getSupportedSourceVersion in interface Processor
- getTypeUtils
  
  public final Types getTypeUtils()
  
  Specified by:
  
  getTypeUtils in interface ProcessingEnvironment
- isEnumType
  
  public final boolean isEnumType(TypeMirror type)
  
  Determines whether the given instance of TypeMirror is for an Enum type.
  
  Specified by:
  
  isEnumType in interface APHelper
  
  Parameters:
  
  type - The type to check.
  
  Returns:
  
  true if the given type is an Enum type, false otherwise.
- init
  
  public final void init(ProcessingEnvironment processingEnv)
  
  Specified by:
  
  init in interface Processor
- printMessage
  
  public final void printMessage(Diagnostic.Kind kind, CharSequence msg)
  
  Specified by:
  
  printMessage in interface APHelper
  
  Specified by:
  
  printMessage in interface Messager
- printMessage
  
  public final void printMessage(Diagnostic.Kind kind, CharSequence msg, Element element)
  
  Specified by:
  
  printMessage in interface APHelper
  
  Specified by:
  
  printMessage in interface Messager
- printMessage
  
  public final void printMessage(Diagnostic.Kind kind, CharSequence msg, Element element, AnnotationMirror annotation)
  
  Specified by:
  
  printMessage in interface APHelper
  
  Specified by:
  
  printMessage in interface Messager
- printMessage
  
  public final void printMessage(Diagnostic.Kind kind, CharSequence msg, Element element, AnnotationMirror annotation, AnnotationValue value)
  
  Specified by:
  
  printMessage in interface APHelper
  
  Specified by:
  
  printMessage in interface Messager
- process
  
  public abstract boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnvironment)
  
  Specified by:
  
  process in interface Processor
- retrieveAnnotatedField
  
  protected final Optional<VariableElement> retrieveAnnotatedField(RoundEnvironment roundEnvironment, Class<? extends Annotation> annotationClass) throws IllegalAnnotationError
  
  Retrieves the field that is annotated with the given annotation. The expectation is that there is just one
  
  Parameters:
  
  roundEnvironment - The environment for information about the current and prior round as set to process(Set, RoundEnvironment).
  
  annotationClass - The class of the annotation.
  
  Returns:
  
  An instance of Optional that holds the field.
  
  Throws:
  
  IllegalAnnotationError - The annotation is invalid.
  
  CodeGenerationError - Multiple fields are annotated with the given annotation.
- retrieveArgumentNames
  
  public final List<Name> retrieveArgumentNames(ExecutableElement method)
  
  Retrieves the names of a method's arguments.
  
  This method will return the names of the arguments as defined only if the compiler flag -parameters is set; otherwise, the arguments are just counted (arg0, arg1, arg2, …).
  
  Specified by:
  
  retrieveArgumentNames in interface APHelper
  
  Parameters:
  
  method - The method.
  
  Returns:
  
  The names of the arguments.
- retrieveGenericTypes
  
  public List<TypeMirror> retrieveGenericTypes(TypeMirror type)
  
  Retrieves the generic types for the given type.
  
  Specified by:
  
  retrieveGenericTypes in interface APHelper
  
  Parameters:
  
  type - The TypeMirror instance to inspect.
  
  Returns:
  
  The type arguments the given type was defined with; will be the empty list if that type was not generic.
- retrieveInterfaces
  
  public final void retrieveInterfaces(TypeElement typeElement, Set<? super TypeElement> interfaces)
  
  Retrieves the interfaces are that implemented or extended by the given type element.
  
  Specified by:
  
  retrieveInterfaces in interface APHelper
  
  Parameters:
  
  typeElement - The type element to inspect.
  
  interfaces - The already retrieved interfaces.

Class APBase

UML Diagram for "org.tquadrat.foundation.ap.APBase"

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.tquadrat.foundation.ap.APHelper

Methods inherited from interface javax.annotation.processing.Messager

Methods inherited from interface javax.annotation.processing.ProcessingEnvironment

Field Details

PACKAGE_NAME

ADD_DEBUG_OUTPUT

MAVEN_GOAL

MSG_AnnotationOnlyForFields

MSG_FieldsOnly

MSG_IllegalAnnotationUse

MSG_MultipleElements

MSG_MultipleFields

MSG_StringConstantRequired

m_AddDebugOutput

m_ElementUtils

m_Environment

m_Filer

m_IsMavenActive

m_Messager

m_Options

m_TypeUtils

Constructor Details

APBase

Method Details

addDebugOutput

composeMessage

getCompletions

getElementUtils

getFiler

getLocale

getMessager

getOption

getOptions

getSourceVersion

getSupportedAnnotationClasses

getSupportedAnnotationTypes

getSupportedOptions

getSupportedSourceVersion

getTypeUtils

isEnumType

init

printMessage

printMessage

printMessage

printMessage

process

retrieveAnnotatedField

retrieveArgumentNames

retrieveGenericTypes

retrieveInterfaces