Xanno Guidelines and Requirements

Requirements

It seems that in order to obey the first concept rule (adding custom annotation and custom annotation processing should be as simple as possible), Xanno needs to implement a servlet/jsp-like mechanism. The design, therefore, introduces the concept of "codelet/fig".
A codelet is the equivalent of a servlet. A codelet is code that processes specific annotations. Each codelet must define which annotations it processes.
fig - File Generation template. A fig template is the equivalent of a jsp page. This template incorporates end-result as-is constants and code that generates dynamic results at annotation processing time.
The fig template includes tags, just like jsp tags. Xanno should provide as many tags as possible to perform common tasks, such as iterate, print values of variables, print common constructs, etc.
All custom annotation processing done by Xanno should be defined in fig templates. These templates will be added to the distribution version of Xanno.
fig templates will be compiled into codelets.
Much like the servlet/jsp mechanism, the codelet/fig mechanism should define an equivalent to the session, page, request, response contexts: session, code, annotation and generating.
A mechanism for compiling and adding 3rd party fig templates should be implemented.
This project really needs an ant task that would run apt. I'm inclined to wait until someone at apache writes one, I assume it's a matter of time, but if not that I would need to write one of my own

Guidelines and Other Thoughts

The project should contain the following modules:

fig compiler - compile fig templates into codelets
codelet processor - runs the codelets while processing annotations

Generating a file requires:

knowing the location of file being generated

source tree or class tree
package name

knowing the name of file being generated
knowing the name of class being processed
having all the annotation instances relevant to the generated file
having all the mirrors of the sources relevant to the generated file
having the output stream (consider using an output stream wrapper to disallow the close operation)

The annotation processing process is as follows:

the programmer starts the pre-compilation process (using apt)
apt locates all available factories, among them the Xanno factory
when an annotation that the Xanno factory can handle is found apt invokes the factory which produces an annotation processor
the annotation processor finds the appropriate codelet to handle each annotation in the file being processed
the annotation processor creates the file(s) the codelet declares it needs to generate
the annotation processor save the relevant annotation instance with all the information the codelet might need (file name being processed, instance of file mirror, etc.)
when the round ends the annotation processor runs all the codelets it found earlier passing all the information saved to each codelet.
when each codelet completes its associated file(s) is closed

This is done this way to allow multiple source files and multiple annotations in each file to contribute to a single generated file. When the codelet runs everything is already known - all the annotations that contributed to the generation of the file, and all the files relevant.
For example, when generating a web.xml we need to know about all the servlets, filters, listeners, etc. in the system. We can only know about them at the end of the round.

The Xanno Project - Guidelines and Requirements