What Is Anakia?

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 E ) { 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 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. In addition to the project.xml based context, additional xml contexts can be added through context nested elements. 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 this website. You can view the source for this website in the "xdocs" folder in the Velocity source distribution.

Installation/Example

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

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

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

The 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.

How does it work?

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

<project name="build-site" default="docs" basedir="."> <property name="docs.src" value="../xdocs"/> <property name="docs.dest" value="../docs"/> <target name="prepare"> <available classname="org.apache.velocity.anakia.AnakiaTask" property="AnakiaTask.present"/> </target> <target depends="prepare" name="prepare-error" unless="AnakiaTask.present"> <echo> AnakiaTask is not present! Please check to make sure that velocity.jar is in your classpath. </echo> </target> <target name="docs" depends="prepare-error" if="AnakiaTask.present"> <taskdef name="anakia" classname="org.apache.velocity.anakia.AnakiaTask"/> <anakia basedir="${docs.src}" destdir="${docs.dest}/" extension=".html" style="./site.vsl" projectFile="./stylesheets/project.xml" excludes="**/stylesheets/**" includes="**/*.xml" lastModifiedCheck="false" velocityPropertiesFile="velocity.properties"> </anakia> <copy todir="${docs.dest}/images" filtering="no"> <fileset dir="${docs.src}/images"> <include name="**/*.gif"/> <include name="**/*.jpeg"/> <include name="**/*.jpg"/> </fileset> </copy> </target> </project>
Name Description
basedir Specifies the path to the directory location of your .xml files.
destdir Specifies the path to the directory where the output files should go.
extension This is the extension that is appended to the end of your .xml file. For example, with an extension of ".html", index.xml would be converted into index.html. By default, the extension is .html.
style This is the path (relative to Velocity's template.loader.1.template.path) to the VelocityStyleTemplate to process. This file is the equivalent to the .xsl file in Ant's style task.
projectFile This is the path to a "project" file. This file is an XML file that can be used as a "navigation" file. If you have used Stylebook or Struts system for generation of the web site documentation, you will understand the purpose of this file. It is an optional task argument. If you look at the Anakia example in the examples/anakia directory, you can see the project.xml file being used in the .vsl file.
excludes This is the standard Ant excludes attribute. Specify any files or directories that you do not want Anakia to try to process.
includes This is the standard Ant includes attribute. Specify any files or directories that you do want Anakia to try to process.
lastModifiedCheck This turns on or off the ability to check the last modified date on files in order to determine whether or not they need to be re-rendered or not. The value of this attribute can be "true, false, yes, no". By default, it is true, meaning that the last modified date should be checked and if the original .xml file, project file, or .vsl file have not changed, then don't process the page. This accelerates processing because pages that have not changed will not get reprocessed.
templatePath This is the path to the templateRoot which is the directory where your site.vsl file is located. This can be defined in the Velocity.properties or it can be defined here. It it an optional argument if it is defined in the Velocity properties file already. However, if defined, this value will override the path defined in the Velocity.properties file.
velocityPropertiesFile This is the path to the velocity.properties file. It is an optional argument and by default is set to find the properties file in the same directory that the JVM was started in.

Predefined Context Objects

The Anakia Ant task places several objects into the Context for you.

, but not the actual . NOTE: this object is obsoleted as simply specifying $element.content will produce the desired output.
Name Value
$root This contains the JDOM root Element to your .xml document. When this (or any other variable containing an element) are simply placed into template output, their XML form is rendered.
$project This contains the JDOM root Element to your project.xml document. If you have not specified a project.xml document, then this variable will not be in the context.
$escape.getText($string) This context object will convert HTML Entities in the $string that is passed into it and it will return the converted String. This is good for dealing with CDATA. The entities that are converted are: " -> " | < -> < | > -> > | & - > &
$relativePath This contains a String which is the relative path to your .xml document from the baseDir that was specified in your Ant task attributes. Please see the examples/anakia .vsl document for example usage of this String.
$xmlout This contains an class which extends the instance of the JDOM XMLOutputter() object. This allows you to easily create String output out of your JDOM element objects. $xmlout.outputString(Element). Again, please look at the examples for more information on how to use this object. NOTE: this object is obsoleted as simply specifying $element will output the XML serialized form of the element.
$xmlout.outputString(Element, true) This contains an class which extends the instance of the JDOM XMLOutputter() object. The difference between this .outputString() and the one in XMLOutputter is that it will output all of the Elements within the passed in Element. So, if you pass in a Element, you will get everything inside the
$treeWalk.allElements($element) This will allow you to walk a tree of JDOM Element objects starting at $element. The point of this context object is to allow you to build an XSLT type system where you can look at each Element node conditionally and set its content and attribute values. This is probably one of the more "ugly" aspects of Anakia, but it does do the job and suggestions for improvement are appreciated. This context object is still under development and more documentation will follow soon. NOTE: this object is obsolete and is kept for backward compatibility only. You can use $element.selectNodes("//*") to achieve the same effect.
$xpath.applyTo("document/properties/@title", $root) The W3C XPath Specification http://www.w3.org/TR/xpath/ refers to NodeSets repeatedly, but this implementation simply uses java.util.List to hold all Nodes. A 'Node' is any object in a JDOM object tree, such as an org.jdom.Element, org.jdom.Document, or org.jdom.Attribute. Please see the .vsl example file and the org.apache.velocity.anakia.XPathTool javadoc for more information. NOTE: this object is obsolete and is kept for backward compatibility only. You can use $element.selectNodes("document/properties/@title") to achieve the same effect with a more intuitive syntax.
$date This is a new java.util.Date object. Useful for putting the current date/time into a page.

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.

Customizing the Anakia Context

The Anakia context can be customized by using one or more context nested elements.

<anakia ...> <context name="customContext" file="./customContext.xml"/> </anakia>

The context file must be an xml file and is an instance of a JDOM root element similar to $project. There are two attributes for the context:

Name Description
name This sets the name of the context within the velocity context. It cannot be one of the predefined context objects.
file The location of the custom file relative to the anakia basedir. This must be an XML file.

Within the velocity template the context can be accessed using the standard velocity template language.

#set ($customMenus = $xpath.applyTo("body/menu",$customContext)) #foreach($customMenu in $customMenus) <strong>$customMenu.getAttributeValue("name")</strong> <ul> #foreach ($customItem in $customMenu.getChildren() ) #set ($name = $customItem.getAttributeValue("name")) <li>#projectanchor($name $customItem.getAttributeValue("href"))</li> #end </ul> #end

Credits

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. The custom context nested element was added by Peter Ryan.