Velocity

Velocityについて

コミュニティ

ドキュメント

比較

ツール

Anakiaとは?

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

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

  1. JDOMドキュメント内でXMLを解析:
    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.put("root", root );
  3. Velocityを使ってテンプレートをレンダリングします。 テンプレート内部で、XML文書に含まれるデータにアクセスするのに JDOMのメソッドが使用できます。

Anakiaは、もしかすると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サイト(例えばjakarta.apache.org.のサイト)のためにとても重要です。 特定の目的に重点を置くため、XSLの「特別な」機能の一部は提供しません。

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

Anakiaは、あなたのproject.xmlページの(オプションの)JDOM文書オブジェクトと同様にコンテキスト(それは.xmlページのJDOM文書オブジェクトを含みます)を生成します。 .vslページは、コンテキストで実行されます(Velocityを使うこと)。 あなたは、それからあなたの.xmlファイルを進むことができて、 単にJDOM文書オブジェクトでメソッドを実行することによってそれから情報を引き出すことができます。

Anakiaは、このWebサイトのドキュメントを作成するためだけでなく、Jakartaプロジェクトで活動している多くのプロジェクトも同様にJakartaプロジェクトのWebサイトや、ドキュメンテーションをつくるためにも使われています。 この過程は、サイト上のdocumentedにあります。 あなたは、自由にあなた自身のニーズのためにもこれを使うことができます。


インストール/サンプル

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

Velocityビルド後、 cd コマンドで、 jakarta-velocity/examples/anakia/build ディレクトリに移動して、 ./build.shを実行します。 (シェルスクリプトは、Windows環境でも Cygwinをインストールしていれば動くでしょう。)

build.shスクリプトの出力(この場合にはHTMLファイル)が、 jakarta-velocity/examples/anakia/docs/ ディレクトリにあります。

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


どうやって動くの?

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>
名前 説明
basedir あなたの .xmlファイルのディレクトリ位置のパスを指定
destdir 出力ファイルの宛先ディレトクリパスを指定
extension これは、.xmlファイルの後ろに追加する拡張子。例えば、".html"の拡張子であれば、 index.xml は、変換されると index.html になる。デフォルトでは .html
style これは、処理するためのVelocityStyleTempleteの (Velocityの template.loader.1.tempalte.pathに関連した)パス。 このファイルは、Antのstyleタスク内で .xslファイルと同等
projectFile これは、「project」ファイルへのパスです。 このファイルは、「navigation」ファイルとして使うことができるXMLファイルです。 あなたがWebサイト・ドキュメンテーションの生成のためにスタイルブックまたはStrutsシステムを使用したならば、あなたはこのファイルの目的が分かるでしょう。 それはオプションのタスクの引数です。 あなたがjakarta-velocity/examples/anakiaディレクトリにおいてAnakiaの例であなたに見えるならば、 .vslファイルにおいて使用されているproject.xmlファイルを見ることができます
excludes これは、標準Ant実行属性です。Anakiaに処理させたくない、 ファイルやディレクトリを指定します
includes これは、標準Antのinclude属性です。Anakiaに処理させたいファイルやディレクトリを 指定します。
lastModifiedCheck これは、再レンダリングするかしないかを判断するためにファイルの最終更新日 をチェックするかどうかをon/offするものです。 この属性の値は、「true, false, yes, no」です。 デフォルトは、trueで、最終修正日付がチェックされます。 そして、オリジナルの.xmlファイル、プロジェクト・ファイルまたは.vsl ファイルに変更が無い場合には、そのページは処理されません。 変更が無いページは再処理されないので、これは処理が早くなります。
templatePath これは、あなたのsite.vslファイルの場所のディレクトリを指定するtemplateRootへのパスです。 これはVelocity.propertiesまたはここで、定義することができます。 Velocityプロパティ・ファイルがすでに定義されていれば、それはオプションの引数です。 しかし、定義されるならば、この値はVelocity.propertiesファイルにおいて定義されるパスをオーバーライドすることになります。
velocityPropertiesFile これは velocity.propertiesファイルへのパスです。 オプションの引数で、デフォルトでは、JVMを開始したのと同じディレクトリにある プロパティファイルです。


Contextオブジェクト

Anakia Ant タスクは、あなたのためにコンテキストにいくつかのオブジェクトを置きます。 たった今、あなたはそうであることに対する支配をコンテキストに置いておきません。 結局、我々はあなたにこれに対する支配を与えるために方法を持つことを望みます。 しかし、それはAnakiaが今日あなたにとても役立つのを妨げません。 :)、あなたの.vslテンプレートであなたが利用できるオブジェクトがあります:

Name Value
$root あなたの .xmlドキュメントへの JDM root要素を含みます。
$project これは、あなたの project.xmlドキュメントへの JDOM root 要素を含みます。 もし project.xmlドキュメントが指定されない場合には、 この値はcontextになりません。
$escape.getText($string) これは、 CDATAのそれにパスされる$stringで、このコンテキスト・オブジェクトはHTMLエンティティを変換します、そして、それは変換した文字列を返すことになります。 これは、CDATAを扱うために良いです。 変換されるエンティティは、以下の通りです " -> &quot; | < -> &lt; | > -> &gt; | & - > &amp;
$relativePath これは、あなたのAntタスク属性において指定されたbaseDirからのあなたの.xml文書への 関連しているパスであるストリングを含みます。 examples/anakiaの .vsl文書(例えばこのストリングの使い方)を見てください。
$xmlout これは、JDOM XMLOutputter()オブジェクトのインスタンスを拡張するクラスを含みます。 これは、あなたのJDOM要素オブジェクトから簡単にストリング出力をつくるためにあなたを許します。 $xmlout.outputString(Element). もう一度、このオブジェクトを使用する方法で詳細は例を見てください。
$xmlout.outputString(Element, true) これは、JDOM XMLOutputter()オブジェクトのインスタンスを拡張するクラスを含みます。 XMLOutputterでのこの.outputString()とものの違いは、それが要素においてパスして 要素内部の全てを出力することになるということです。 つまり、<td> 要素内に渡すとすべて <td> </td>内部を得ることになりますが、 正確には<td> </td>ではありません。
$treeWalk.allElements($element) これは、$elementから始まっているJDOM要素オブジェクトのツリーを歩くためにあなたを許すことになります。 このコンテキスト・オブジェクトの点は、構築するためにあなたを許すことですあなたが条件的に各要素ノードを見ることができて、その内容と属性値をセットすることができるXSLTタイプ・システム。 これは多分Anakiaのより「醜い」面のうちの1つであるでしょう、しかし、それは仕事をします、そして、改良のための提案は認められます。 このコンテキスト・オブジェクトはさらに開発中です、そして、より多くのドキュメンテーションはすぐに追従することになります。
$xpath.applyTo("document/properties/@title", $root) W3C XPath 仕様http://www.w3.org/TR/xpath/ 繰り返してNodeSetsを呼びます、 しかし、この実装は、単に全てのノードを保持するためにjava.util.Listを使います。 『ノード』は、JDOMオブジェクト・ツリー(例えばorg.jdom.Element、org.jdom.Documentまたはorg.jdom.Attribute)でのどんなオブジェクトでもあります。 詳細は.vsl例ファイルとorg.apache.velocity.anakia.XPathTool javadocを見てください。
$date これは、新しいjava.util.Dateオブジェクトです。 現在の日付/時刻をページに入れることに役立ちます。


Credits

Anakiaのオリジナルのコンセプト化と実装は、Jon S. Stevensによって行なわれました。

Anakiaという名前は、 私が非常にうまくこのプロジェクトに合うと思ういかした名前です。 「Anakiaという名前は、独創的方法で、創造的で、芸術的で、音楽的な表現を 想像させます。 あなたが、障害にもかかわらず、何かをやり抜くために必要な忍耐を持つので、 あなたは異なって、あなたの考えを実装するために自身信頼を持とうと努力します。」

多くの援助や協力は、Jason van ZylとGeir Magnusson Jr.によって 提供されました。XPathのサポートはBob McWhirterによって追加されました。



このドキュメントは、 熊坂祐二 が訳しました。コメントがある場合は、 jajakarta-report@jajakarta.good-day.net までお願いします。
Copyright © 1999-2001, Apache Software Foundation