Anakia

Anakia Jon S. Stevens 熊坂祐二新穂洋史高橋達男 anakia

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

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

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( ...  );
}

ドキュメント (または root 要素) をcontextに入れます。
```
context.put("root", root );
```
Velocity を使ってテンプレートを処理します。テンプレート内部で、XML 文書に含まれるデータにアクセスするために JDOM のメソッドを利用できます。

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

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

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

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

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

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

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

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

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

AnakiaTaskが見つかりません。クラスパスにvelocity.jarが含まれているかどうか確認してください。 ]]>

名前	説明
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 標準の exclude 属性です。 Anakia に処理させたくないファイルやディレクトリを指定します
includes	これは、Ant 標準の include 属性です。 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 を起動したのと同じディレクトリにあるプロパティファイルです。

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

Name	Value
$root	あなたの.xmlドキュメントへの JDOM root 要素が含まれています。これを単にテンプレート出力に記述すると、その XML 形式が処理されます (要素に含まれる他のどんな変数も同様です)。
$project	project.xml ドキュメントへの JDOM root 要素が含まれています。もし project.xml ドキュメントが指定されていない場合には、この変数はコンテキストに含まれません。
$escape.getText($string)	このコンテキストオブジェクトは、引数として渡された $string を HTML エンティティに変換し、変換結果を String 型で返します。これは、CDATA を扱うのに便利です。変換されるエンティティは、以下の通りです " -> " \| < -> < \| > -> > \| & -> &
$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 オブジェクトです。現在の日付/時刻をページに入れるのに役立ちます。

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

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

Anakia のオリジナルのコンセプト化と実装は、 Jon S. Stevens が行いました。

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

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