The main concepts behind the design are:

  • Adding custom annotations and custom annotation processing should be as simple as possible.
  • Xanno should not write its own parse to source files
  • Xanno should always rely on standard Sun-issued tools.
  • Xanno should come with as extensive as possible custom annotations variety.

  • 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

  • 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:
    1. the programmer starts the pre-compilation process (using apt)
    2. apt locates all available factories, among them the Xanno factory
    3. when an annotation that the Xanno factory can handle is found apt invokes the factory which produces an annotation processor
    4. the annotation processor finds the appropriate codelet to handle each annotation in the file being processed
    5. the annotation processor creates the file(s) the codelet declares it needs to generate
    6. 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.)
    7. when the round ends the annotation processor runs all the codelets it found earlier passing all the information saved to each codelet.
    8. 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.
Sourceforge Xanno