The Xanno Project

Notice 21-oct-2005

Development on this project has ceased since the introduction of xdoclet's jdk-1.5 compatiability patch. To install the patch:

• rename file to xjavadoc-1.1.jar
• overwrite original xjavadoc file placed at XDOCLETS_HOME/lib

While this patch allows the usage of triangle brackets in generics (>,<), it does not recognize method-level annotations. Even though I've decided that this is enough for the mean time, and have decided to stop putting efforts into this project.
If you wish to continue (or rather start) development - contact me via sourceforge, and I will hand the project over to you.

End of notice

The Xanno project (pronounced zan-no) is an annotation-based file generation tool. This project is a sourceforge.net project.

The main idea behind the project is to create a next generation XDoclet project.
The XDoclet project is based on javadoc technology. This technology was the only one that could create annotation-like structures at the time XDoclet started.
However, since the introduction of annotations, the use of javadoc to generate code has been, for a lack of better word, deprecated. Current version of jdk dictate that code generation should be performed as an integral part of the compilation process, and, in fact, Sun has released with the jdk a new tool called apt.
Apt can be used either as a pre-compiler for Java source, or instead of the javac compiler. Some people even argue that the javac compiler should be deprecated and that apt should always be used even if there are no annotations in the source.

Anyway, Apt allows for the extension of the annotation mechanism. It allows the programmer to write annotations processing for custom annotations. Essentially this is what I'm trying to do here - define a convenient way to create custom annotations and process them.

In general, I expect more and more project would start using annotations. The new EJB 3.0 standard uses runtime annotations, as does any JSR-220 compliant implementation. Obviously, sometime in the not-so-near future this project will be rendered useless, because everyone would use annotations and provide processors for them anyway. In the mean time, until this happens, I think this project has merit.

The plan has several stages:

• Proof of concept
• Design
• Execution

The proof of concept is over. The current version of the project - 0.1 is a proof of concept that actually creates a valid web.xml file with servlet, servlet-mapping, filter, filter-mapping and listener sections. It can also merge out-side section defined in a merge dir.

I am now at the design stage. I'm witting a requirements and guidelines document and intend to write a detailed design document that will define how everything should look like in version 1.0. I've defined the following design concepts based on my experience with using XDoclet

• Adding custom annotations and custom annotation processing should be as simple as possible.
• Xanno should not write its own parse to source files - this is what is causing, in my opinion, the demise of the XDoclet project. Xanno should always rely on standard Sun-issued tools.
• Xanno should come with as extensive as possible custom annotations variety, but should start with the most common uses. In my experience this should be - web.xml, struts-config.xml, ejb 2.x related files - in this order. Hibernate is also important, but they are working on adding their own annotations to comply with JSR-220.

The execution stage - well, that's obvious.

The current release is the proof of concept (version 0.1). The files in the release are:

• sources - source release. From this release you can build all other releases
• annotations - any project that uses Xanno annotations require this jar in its classpath. This jar includes the definition of the Xanno annotations. This jar may be required during runtime in the future, if I'll add runtime annotations (currently all annotations are source annotations).
• factories - this jar is required by apt to process Xanno annotations. It is a compile-time only jar for projects that use Xanno annotations, and not required during runtime.