Package org.glassfish.apf

Interface AnnotationProcessor

All Known Implementing Classes:

AnnotationProcessorImpl

public interface AnnotationProcessor

The annotation processor is the core engine to process annotations. All the processing configuration (input classes, error handlers, etc...) is provided by the ProcessingContext which can be either created from the createContext method or through another mean. Once the ProcessingContext has been initialized, it is passed to the process(ProcessingContext ctx) method which triggers the annotation processing.

Each class accessible from the ProcessingContext.getInputScanner instance, will be scanned for annotations. Each annotation will then be processed by invoking the corresponding AnnotationHandler from its annotation type.

The AnnotationProcessor can be configured by using the pushAnnotationHandler and popAnnotationHandler which allow new AnnotationHandler instances to be registered and unregistered for a particular annotation type.

Even without reconfiguring the AnnotationProcessor instance with the above configuration methods, the AnnotationProcessor implementation cannot guarantee to be thread safe, therefore, it is encouraged the make instanciation cheap and users should not use the same instance concurrently.

Author:

Jerome Dochez

Method Summary

Modifier and Type	Method	Description
ProcessingContext	createContext()	Creates a new empty ProcessingContext instance which can be configured before invoking the process() method.
AnnotationHandler	getAnnotationHandler(Class<? extends Annotation> type)
AnnotatedElement	getLastAnnotatedElement(ElementType type)
void	log(Level level, AnnotationInfo locator, String localizedMessage)	Log a message on the default logger
void	popAnnotationHandler(Class<? extends Annotation> type)	Unregisters the last annotation handler registered for an annotation type.
ProcessingResult	process(ProcessingContext ctx)	Starts the annotation processing tool passing the processing context which encapsulate all information necessary for the configuration of the tool.
ProcessingResult	process(ProcessingContext ctx, Class[] classes)	Process a set of classes from the parameter list rather than from the processing context.
void	pushAnnotationHandler(AnnotationHandler handler)	Registers a new AnnotationHandler for a particular annotation type.

Method Detail

createContext

ProcessingContext createContext()

Creates a new empty ProcessingContext instance which can be configured before invoking the process() method.

Returns:

an empty ProcessingContext

process

ProcessingResult process(ProcessingContext ctx)
                  throws AnnotationProcessorException

Starts the annotation processing tool passing the processing context which encapsulate all information necessary for the configuration of the tool.

Parameters:

ctx - is the initialized processing context

Returns:

the result of the annotations processing

Throws:

AnnotationProcessorException

process

ProcessingResult process(ProcessingContext ctx,
                         Class[] classes)
                  throws AnnotationProcessorException

Process a set of classes from the parameter list rather than from the processing context. This allow the annotation handlers to call be the annotation processing tool when classes need to be processed in a particular context rather than when they are picked up by the scanner.

Parameters:

ctx - the processing context

classes - the list of classes to process

Returns:

the processing result for such classes

Throws:

AnnotationProcessorException - if handlers fail to process an annotation

pushAnnotationHandler

void pushAnnotationHandler(AnnotationHandler handler)

Registers a new AnnotationHandler for a particular annotation type. New annotation handler are pushed on a List of annotation handlers for that particular annotation type, the last annotation handler to be registered will be invoked first and so on. The annotation type handled by the AnnotationHandler instance is defined by the getAnnotationType() method of the AnnotationHandler instance

Parameters:

type - the annotation type

handler - the annotation handler instance

getAnnotationHandler

AnnotationHandler getAnnotationHandler(Class<? extends Annotation> type)

Parameters:

type - the annotation type

Returns:

the top annotation handler for a particular annotation type

popAnnotationHandler

void popAnnotationHandler(Class<? extends Annotation> type)

Unregisters the last annotation handler registered for an annotation type.

Parameters:

type - the annotation type.

getLastAnnotatedElement

AnnotatedElement getLastAnnotatedElement(ElementType type)

Returns:

the most recent AnnotatedElement being processed which type is of the given ElementType or null if there is no such element in the stack of processed annotation elements.

log

void log(Level level,
         AnnotationInfo locator,
         String localizedMessage)

Log a message on the default logger