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.

基本的に Anakia は JDOM と Velocity を用いて、XML 文書を好きなフォーマットに変換できる XML 変換ツールです。 Anakia は、XML ファイルを処理する Ant の <style> タスクと XSL に替わる機能を提供します。

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.

AnakiaTask が使う基本モデルは、かなり簡単です。

1. XML をパースしてJDOM ドキュメントに変換します。
   

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

2. ドキュメント (または root 要素) をcontextに入れます。
   

   context.put("root", root );

3. Velocity を使ってテンプレートを処理します。 テンプレート内部で、XML 文書に含まれるデータにアクセスするために JDOM のメソッドを利用できます。

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 は、XSL よりも簡単に覚えられますが、 XSL と同じレベルの機能を提供します。 暗号のような <xsl:> タグを学ぶ必要はもうありません; 提供されたコンテキストオブジェクトや、JDOM、それに Velocity の単純な指示子を使う方法を知る必要があるだけです。 Anakia は、Xalan の XSL プロセッサと比べ、非常に高速にページを生成するようです （23 ページを生成するのに、JDK1.3 とクライアント Hotspot で Pentium III の 500MHz の Win98 上で 7 - 8 秒で生成します。Ant の <style> タスクを使った同じようなシステムでは 14 - 15 秒で、約 2 倍の速度差があります。）

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.

Anakia は、Stylebook の置き換えを目的としています。 Stylebook は、元々全てのページが同じ見た目を持つような単純で静的な Web サイトを生成するために使われました。Anakia は、ドキュメンテーション/プロジェクトの Web サイト（例えば www.apache.org サイト や jakarta.apache.org サイト ）に最適です。 Anakia は、使用目的を絞り込むことで、XSL の「余分な」機能の一部は提供しません。

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

jakarta-velocity/examples/anakia ディレクトリにあるサンプルは Anakia のうまい使い方を示しています。 このサンプルを見れば、Anakia が非常に使いやすことが分かるはずです。

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 は コンテキストを生成します。コンテキストには、.xml ページや (オプションで) project.xml ページの JDOM 文書 オブジェクトを含められます。 .vsl ページは、(Velocity を使って) このコンテキストと一緒に処理されます。 そのため、JDOM 文書オブジェクトのメソッドを実行するだけで、.xml ファイルをたどってそこから情報を引き出すことができます。

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.

Anakia は、この Web サイトのドキュメント作成だけでなく、 Jakarta プロジェクトのWebサイトや Jakarta プロジェクト内の多くのサブプロジェクトで、ドキュメント生成に利用されています。 この手順については、サイト上に記述されています。 これを個人的に使うのも自由です。

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

jakarta-velocity/examples/anakia を評価する前に、 Velocity をビルドする必要があります。

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

Velocity ビルド後、 cd コマンドで、 jakarta-velocity/examples/anakia/build ディレクトリに移動して、 「ant」を実行します。

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

ant の実行結果(この場合には HTML ファイル)は、 jakarta-velocity/examples/anakia/docs/ ディレクトリに出力されます。

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.

jakarta-velocity/examples/anakia/xdocs/ ディレクトリに、全ての .xml ソースコードがあります。 xdocs/stylesheets ディレクトリには.vsl ファイルがありますが、 Anakiaの魔法の大部分はここで行われます。 .vsl ファイルの動作を理解するには、 Velocity テンプレート言語 と JDOM を理解する必要があります。

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

Anakia は、Ant ビルドファイルから起動される Ant タスクです。ビルドファイルは 以下のようになります。

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

	<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が見つかりません。クラスパスにvelocity.jarが 含まれているかどうか確認してください。 </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 jakarta-velocity/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.

名前	説明
basedir	.xml ファイルがあるディレクトリのパスを指定します。
destdir	出力ファイルの宛先ディレトクリパスを指定します。
extension	.xml ファイルの後ろに追加する拡張子です。例えば、拡張子が　".html" であれば、 index.xml は、index.html に変換されます。デフォルトの拡張子は .html です。
style	処理対象のVelocityStyleTemplate へのパス (Velocityの template.loader.1.template.path 基準の相対パス)です。 このファイルは、Ant の style タスクの .xsl ファイルと同等です。
projectFile	「project」ファイルへのパスです。 このファイルは、「ナビゲーション」ファイルとして使うことができる XML ファイルです。 もし Web サイトのドキュメントの生成のために StyleBook や Struts のシステムを使用したことがあれば、このファイルの目的は分かるでしょう。 これは省略可能なタスク引数です。 jakarta-velocity/examples/anakia ディレクトリにある Anakia のサンプルで、 project.xml ファイルが .vsl ファイルで使用されているのを見ることができます。
excludes	これは、Ant 標準の excludes 属性です。 Anakia に処理させたくないファイルやディレクトリを指定します
includes	これは、Ant 標準の includes 属性です。 Anakia に処理させたいファイルやディレクトリを指定します。
lastModifiedCheck	再処理するかどうかを判定するためのファイルの最終更新日時のチェック機能をオンまたはオフにします。 この属性は、「true, false, yes, no」のいずれかの値をとることができます。 デフォルトの値は true で、最終更新日時がチェックされます。 そして、元の .xml ファイル、プロジェクトファイルや .vsl ファイルに変更が無い場合には、そのページは処理されません。 変更が無いページは再処理されないので、処理が早くなります。
templatePath	site.vsl ファイルが置かれたディレクトリである templateRoot へのパスです。 この属性は velocity.properties でも指定できますし、ここで指定することもできます。 velocity.properties ファイルですでに指定していれば、省略可能です。 しかし、ここで指定した場合は、この値は velocity.properties ファイルで指定した値を上書きします。 (訳注：上記の記述に反して、 velocity.properties ファイルを定義したときには templatePath 属性は無視されるようです。 そのため、 velocity.properties ファイルを定義するときには、同等の属性である file.resource.loader.path を指定する必要があります。)
velocityPropertiesFile	これは velocity.propertiesファイルへのパスです。 省略可能で、デフォルトでは、JVM を起動したのと同じディレクトリにある プロパティファイルです。

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:

Anakia Ant タスクは、コンテキストにいくつかのオブジェクトを設定します。 現在のところ、コンテキストにどのオブジェクトを設定するかを制御することはできません。 いつかは、これらを制御する方法を提供したいと思います。 しかしながら、このことは現在 Anakia が極めて便利であることを否定するものではありません。:-) .vsl テンプレートで利用できるオブジェクトは以下のとおりです。

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: " -> &quot; | < -> &lt; | > -> &gt; | & - > &amp;
$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 <td> Element, you will get everything inside the <td> </td>, but not the actual <td> </td>. NOTE: this object is obsoleted as simply specifying $element.content will produce the desired output.
$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.

Name	Value
$root	.xmlドキュメントへの JDOM root 要素が含まれています。 これを単にテンプレート出力に記述すると、 その XML 形式が処理されます (要素に含まれる他のどんな変数も同様です)。
$project	project.xml ドキュメントへの JDOM root 要素が含まれています。 もし project.xml ドキュメントが指定されていない場合には、 この変数はコンテキストに含まれません。
$escape.getText($string)	このコンテキストオブジェクトは、引数として渡された $string を HTML エンティティに 変換し、変換結果を String 型で返します。 これは、CDATA を扱うのに便利です。 変換されるエンティティは、以下の通りです " → &quot; | < → &lt; | > → &gt; | & → &amp;
$relativePath	Ant タスク属性で指定された baseDir を基準にした .xml 文書への相対パスの String が含まれています。この String の使い方については、examples/anakia の .vsl 文書を参照してください。
$xmlout	JDOM XMLOutputter() オブジェクトのインスタンスを extend したクラスが含まれます。 これを使って、JDOM 要素オブジェクトから簡単に String の出力を生成できます。 $xmlout.outputString(Element) これについても、このオブジェクトを使用する方法の詳細は例を見てください。 注意: 単に $element を指定すれば、要素のXMLシリアル化形式を出力できるので、 このオブジェクトは非推奨となっています。
$xmlout.outputString(Element, true)	JDOM XMLOutputter() オブジェクトのインスタンスを extend したクラスが含まれています。 この.outputString() とXMLOutputter.outputString() との違いは、.outputStringでは Elementという引数の内部の要素全てを出力することです。 つまり、<td> 要素を渡すと、 <td> </td>内のすべてのものは取得できますが、 <td> </td> 自身は含まれません。 注意: 単に $element.content を指定すれば、必要な出力を生成できるので、 このオブジェクトは、非推奨となっています。
$treeWalk.allElements($element)	これを使うと $element から始まる JDOM 要素オブジェクトのツリーを渡り歩くことができます。 このコンテキストオブジェクトのポイントは、 XSLTタイプシステムを構築することができるということです。 このXSLTタイプシステムは、各要素ノードを条件をつけて参照したり、 内容や属性値をセットしたり出来ます。 これは多分 Anakia の「美しくない」側面の1つでしょうが、実際問題として効果的なのです。 もちろん改良のための提案は歓迎します。 このコンテキストオブジェクトはまだ開発中で、文書化が追いついていません。 注意: このオブジェクトは非推奨で、下位互換のためのだけに存在しています。 $element.selectNodes("//*") で同じことができます。
$xpath.applyTo("document/properties/@title", $root)	W3C XPath 仕様 http://www.w3.org/TR/xpath/ では、 Node-Setsに繰り返し言及しています。 しかし、この実装では、全てのノードを保持するのに、単純に java.util.List を使います。 「ノード」は、JDOM オブジェクトツリーにおける、org.jdom.Element、org.jdom.Document、 org.jdom.Attribute といった任意のオブジェクトのことです。 詳細は .vsl のサンプルファイルと org.apache.velocity.anakia.XPathToolのjavadoc を見てください。 注意: このオブジェクトは非推奨で、後方互換のためだけに存在しています。 $element.selectNodes("document/properties/@title") を使えば、より直感的な文法で、 同じことができます。
$date	これは、新しい java.util.Date オブジェクトです。 現在の日付/時刻をページに入れるのに役立ちます。

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 オブジェクトから、 $element.selectNodes, $element.content, $element.children を経由して返されたすべてのノードリストは (非推奨である $treeWalk.allElements, $xpath.applyTo 経由で返されたノードリストと同様に) 2つの特別な機能を持っています。

• これらは、単一要素と全く同じように selectNodes メソッドをサポートします。 selectNodesメソッドでリストのすべてのノードにXPath 式を適用できます。
• 単に $list と指定して、テンプレート出力に挿入された時には、 ノードリストが含むすべてのノードから構成される XML 断片を生成します。 これにより、ほとんどの #foreach コードをテンプレートから排除できます。

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

Anakia のオリジナルのコンセプト化と実装は、 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."

Anakia という名前は、 このプロジェクトにピッタリな、かっこいい名前だと思います。カバラ数秘術の名前診断によると、 「Anakia という名前の人は、独自のやり方での創造的、芸術的、音楽的な表現欲求を持っています。 他人と違う自分になろうと努力し、また自分の考えを実行するための自信をもっています。 なぜなら誰かに反対されてもやり遂げるだけの忍耐力があるからです。」

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.

Jason van Zyl と Geir Magnusson Jr. は、いろいろと支援や協力をしてくれました。 XPath のサポートについては、Bob McWhirter が追加してくれました。 Attilia Szegedi は selectNodes() と自己レンダリング要素とノードリストの直感的な文法のほとんどを、 追加してくれました。