Package org.tquadrat.foundation.ap

Interface APHelper

All Superinterfaces:

Messager, ProcessingEnvironment

All Known Implementing Classes:

APBase

@ClassVersion(sourceVersion="$Id: APHelper.java 1061 2023-09-25 16:32:43Z tquadrat $")
@API(status=STABLE,
     since="0.1.0")
public interface APHelper
extends Messager, ProcessingEnvironment

The specification for a set of helpers for annotation processing.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: APHelper.java 1061 2023-09-25 16:32:43Z tquadrat $

Since:

0.1.0

UML Diagram

⁠

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

⁠

Method Summary

Modifier and Type	Method	Description
boolean	addDebugOutput()	Returns the flag that indicates whether some debug information should be emitted to the generated code.
default Optional<? extends AnnotationMirror>	getAnnotationMirror(Element element, Class<? extends Annotation> annotationClass)	Retrieves the AnnotationMirror for the given annotation from the given Element instance.
default Optional<? extends AnnotationValue>	getAnnotationValue(AnnotationMirror annotationMirror)	Retrieves the annotation value from the given annotation mirror.
default Optional<? extends AnnotationValue>	getAnnotationValue(AnnotationMirror annotationMirror, String name)	Retrieves the annotation value with the given name from the given annotation mirror.
default Optional<TypeMirror>	getTypeMirrorFromAnnotationValue(Element element, Class<? extends Annotation> annotationClass)	Retrieves a TypeMirror instance from an annotation.
default Optional<TypeMirror>	getTypeMirrorFromAnnotationValue(Element element, Class<? extends Annotation> annotationClass, String attributeName)	Retrieves a TypeMirror instance from an annotation.
default <A extends Annotation> boolean	hasAnnotation(Element element, Class<A> annotationType)	Checks whether the given element has the given annotation.
boolean	isEnumType(TypeMirror type)	Determines whether the given instance of TypeMirror is for an Enum type.
default void	printMessage(Diagnostic.Kind kind, CharSequence msg)
default void	printMessage(Diagnostic.Kind kind, CharSequence msg, Element element)
default void	printMessage(Diagnostic.Kind kind, CharSequence msg, Element element, AnnotationMirror annotation)
default void	printMessage(Diagnostic.Kind kind, CharSequence msg, Element element, AnnotationMirror annotation, AnnotationValue value)
List<Name>	retrieveArgumentNames(ExecutableElement method)	Retrieves the names of a method's arguments.
List<? extends TypeMirror>	retrieveGenericTypes(TypeMirror type)	Retrieves the generic types for the given type.
default void	retrieveInterfaces(TypeElement typeElement, Set<? super TypeElement> interfaces)	Retrieves the interfaces are that implemented or extended by the given type element.

Methods inherited from interface javax.annotation.processing.Messager

printError, printError, printNote, printNote, printWarning, printWarning

Methods inherited from interface javax.annotation.processing.ProcessingEnvironment

getElementUtils, getFiler, getLocale, getMessager, getOptions, getSourceVersion, getTypeUtils, isPreviewEnabled

Method Details

addDebugOutput

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".

Returns:

true if the debug information should be added, false if not.

getAnnotationMirror

default Optional<? extends AnnotationMirror> getAnnotationMirror(Element element,
 Class<? extends Annotation> annotationClass)

Retrieves the AnnotationMirror for the given annotation from the given Element instance. Only declared annotations are considered, not the inherited ones.

Parameters:

element - The element.

annotationClass - The annotation to look for.

Returns:

An instance of Optional that holds the found AnnotationMirror instance.

See Also:

• Element.getAnnotationMirrors()

getAnnotationValue

default Optional<? extends AnnotationValue> getAnnotationValue(AnnotationMirror annotationMirror)

Retrieves the annotation value from the given annotation mirror.

Parameters:

annotationMirror - The annotation mirror.

Returns:

An instance of Optional that holds the found annotation value.

getAnnotationValue

default Optional<? extends AnnotationValue> getAnnotationValue(AnnotationMirror annotationMirror,
 String name)

Retrieves the annotation value with the given name from the given annotation mirror.

Parameters:

annotationMirror - The annotation mirror.

name - The name of the desired value.

Returns:

An instance of Optional that holds the found annotation value.

getTypeMirrorFromAnnotationValue

default Optional<TypeMirror> getTypeMirrorFromAnnotationValue(Element element,
 Class<? extends Annotation> annotationClass)

Retrieves a TypeMirror instance from an annotation.

In case an annotation defines a Class<?> attribute, the value for that attribute is either null or something strange, but never an instance of Class<?>. So we need some special code to get something useful from the annotation.

This implementations assumes the default name "value" for the attribute.

Parameters:

element - The annotated element.

annotationClass - The type of the annotation.

Returns:

An instance of Optional that holds the TypeMirror instance.

Throws:

NoSuchElementException - The given element is not annotated with an annotation of the given type.

getTypeMirrorFromAnnotationValue

default Optional<TypeMirror> getTypeMirrorFromAnnotationValue(Element element,
 Class<? extends Annotation> annotationClass,
 String attributeName)

Retrieves a TypeMirror instance from an annotation.

In case an annotation defines a Class<?> attribute, the value for that attribute is either null or something strange, but never an instance of Class<?>. So we need some special code to get something useful from the annotation.

Parameters:

element - The annotated element.

annotationClass - The type of the annotation.

attributeName - The name of the attribute that holds the class.

Returns:

An instance of Optional that holds the TypeMirror instance.

Throws:

NoSuchElementException - The given element is not annotated with an annotation of the given type.

hasAnnotation

default <A extends Annotation> boolean hasAnnotation(Element element,
 Class<A> annotationType)

Checks whether the given element has the given annotation.

Note:

• If the retention for the given annotation is not it could have been removed from the element in an earlier compile run.

Type Parameters:

A - The type of the annotation.

Parameters:

element - The element to inspect.

annotationType - The type of the annotation to look for.

Returns:

true if the element is annotated with the given annotation, false if not.

See Also:

• RetentionPolicy.RUNTIME

isEnumType

boolean isEnumType(TypeMirror type)

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

Parameters:

type - The type to check.

Returns:

true if the given type is an Enum type, false otherwise.

printMessage

default void printMessage(Diagnostic.Kind kind,
 CharSequence msg)

Specified by:

printMessage in interface Messager

printMessage

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

Specified by:

printMessage in interface Messager

printMessage

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

Specified by:

printMessage in interface Messager

printMessage

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

Specified by:

printMessage in interface Messager

retrieveArgumentNames

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, …).

Parameters:

method - The method.

Returns:

The names of the arguments.

retrieveGenericTypes

List<? extends TypeMirror> retrieveGenericTypes(TypeMirror type)

Retrieves the generic types for the given type.

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

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

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

Parameters:

typeElement - The type element to inspect.

interfaces - The already retrieved interfaces.