Essentially an XML transformation tool, Anakia uses JDOM and Velocity to transform XML documents into the format of your choice. It provides an alternative to using Ant's <style> task and XSL to process XML files.

The basic model that AnakiaTask uses is pretty straightforward :

1. Parse your XML into a JDOM Document:
   

   SAXBuilder builder;
   Document root = null;
   
   try 
   {
       builder = new SAXBuilder( 
           "org.apache.xerces.parsers.SAXParser" );
       root = builder.build( file );
   }
   catch( Exception )
   {
       System.out.println( ...  );
   }

2. Stuff the Document (or root Element) into the context:
   

   context.put("root", root );

3. Render a template using Velocity. Within the template, one can use JDOM's methods to access the data contained in the XML document.

Anakia is potentially easier to learn than XSL, but it maintains a similar level of functionality. Learning cryptic <xsl:> tags is unnecessary; you only need to know how to use the provided Context objects, JDOM, and Velocity's simple directives. Anakia seems to perform much faster than Xalan's XSL processor at creating pages. (23 pages are generated in 7-8 seconds on a PIII 500mhz running Win98 and JDK 1.3 with client Hotspot. A similar system using Ant's <style> task took 14-15 seconds -- nearly a 2x speed improvement.)

Anakia -- intended to replace Stylebook, which was originally used to generate simple, static web sites in which all pages had the same look and feel -- is great for documentation/project web sites, such as the sites on www.apache.org and jakarta.apache.org. As it is more targeted to a specific purpose, it does not provide some of XSL's "extra" functionality.

The example in the jakarta-velocity/examples/anakia directory provides a good introduction to Anakia. You should find it quite simple to use.

Anakia creates a Context, which contains a JDOM Document object of the .xml page, as well as an (optional) JDOM Document object of your project.xml page. The .vsl page is executed (using Velocity) with the Context. You can then navigate your .xml file and pull information out of it by simply executing methods on the JDOM Document object.

Anakia is being used to create the documentation for not only this website, but also for the Jakarta Project's website as well as many of the projects that live under the Jakarta Project. This process is documented on the site. You are welcome to use this for your own needs as well.

Before reviewing the jakarta-velocity/examples/anakia directory, you must build Velocity.

After building Velocity, cd into the jakarta-velocity/examples/anakia/build directory and run 'ant'.

Output from running ant, in this case HTML files, is placed into the jakarta-velocity/examples/anakia/docs/ directory.

The jakarta-velocity/examples/anakia/xdocs/ directory has all of the .xml source code. The xdocs/stylesheets directory contains the .vsl file, in which most of the magic happens. Understanding Velocity Template Language and JDOM is necessary to understand how the .vsl file works.

Anakia is an Ant task that executes from an Ant build file. The build file looks something like this:

The Anakia Ant task places several objects into the Context for you. Right now, you do not have control over what is placed into the Context. Eventually, we hope to have a way to give you control over this. However, that does not prevent Anakia from being extremely useful for you today. :-) The objects that are available to you in your .vsl template are:

All node lists returned from Anakia objects through $element.selectNodes, $element.content, and $element.children, as well as through obsoleted $treeWalk.allElements and $xpath.applyTo have two special features:

• they support the selectNodes method just as a single element does that applies an XPath expression to all nodes in the list, and
• when inserted into template output by simply specifying $list, they produce the XML fragment consisting of all nodes they contain. This eliminates much of the #foreach code in templates.

Anakia was originally conceptualized and implemented by Jon S. Stevens.

The name Anakia is a cool name that I think fits this project quite nicely. "The name of Anakia has given you the desire for creative, artistic or musical expression in an original way. You strive to be different and have the self-confidence to implement your ideas because you have the perseverance necessary to see something through, despite obstacles."

Further help and assistance was provided by Jason van Zyl and Geir Magnusson Jr. XPath support was added by Bob McWhirter. The more intuitive syntax achieved through selectNodes() and self-rendering elements and node lists was added by Attila Szegedi.