XMLカタログ

XMLカタログは、XMLドキュメント中で参照されるDTDやエンティティ のようなpublicなリソースのカタログです。 カタログは一般的に、web上のリソースをローカルなキャッシュされたコピーへの参照 とするために使われます。

これは、XMLパーサーやXSLTプロセッサー、他のXMLドキュメントを使うツール が、webに存在するリソースを使う代わりに、効果的にローカルのリソースを 使うことを可能にします。

注意:このタスクは、Antディストリビュージョンに含まれない外部のライブラリに依存しません。 詳しくは、ライブラリ依存関係を参照してください。

このデータタイプは OASIS "Open Catalog" standardに基づくリソースのカタログを提供します。 このカタログのエントリーは、 Java API for XML Processing (JAXP) 仕様 として定義されている、 org.xml.sax.EntityResolverjavax.xml.transform.URIResolver インターフェイスに従い、 エンティティ解決とURI解決の両方に使えます。

例えば、web.xmlファイルのDTDは以下のように参照されます。

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
  "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

XMLカタログのサポートがなければ、XMLプロセッサーは、 ドキュメントの妥当性検査が要求される度に、 URLで指定された場所からDTDを取得する必要があります。

これは、ビルドプロセス中で、とても多くの時間がかかる処理です。 特に、ネットワークのスループットが限界の場合にそうなります。 代わりに、次のようにすることができます。

  1. web-app_2_2.dtdをローカルディスクのどこかへコピーします (ファイルシステムか、クラスパス上のjarやzipファイルに組み込みます)。
  2. そのファイルをlocation属性に指定した <dtd>要素を使って、 <xmlcatalog>を作成します。 。
  3. 成功すると、XMLプロセッサーはインターネットの代わりに今のローカルコピーを使います。

XMLカタログは、この機能をサポートするタスク内か、 targetと同じレベルにあらわれます。 すなわち、XML ValidationやXSLT Transformationなどのタスクを、 他のタスクからまたいで再利用するために projectの子供として使用できます。 XML ValidateタスクはXMLカタログをエンティティー解決に使います。 XSLT Transformationタスクは、エンティティーとURI解決の両方に XMLカタログを使います。

XMLカタログは、他のXMLカタログへの参照として指定します。 ビルドファイルの中で前もって定義するか、 あるいは、dtdentityの場所のリストとして、指定します。 さらに、外部のカタログファイルは、 ネストしたcatalogpath内で指定されることができますが、 それらは、システムクラスパス内のxml-commons解決ライブラリが、 利用可能でない限り無視されます。 resolver 1.0のリリース後の、resolver規約内の下位互換性の変更の結果、 Antは、バージョン1.0のresolver.jarをサポートしません。 - Ant 1.6がリリースされる前に、resolver1.1をリリースすると期待しています。 エンティティー解決のための区切られたクラスパスは、 ネストしたclasspath要素によって インラインで指定できます。 クラスパスを指定しない場合は、システムクラスパスが同様に使用されます。

XMLカタログは、他のXMLカタログの中でネストすることができます。 例えば、"superset"のXMLカタログは、前に定義したXMLカタログを参照する、 複数のネストしたXMLカタログを含むことができます。

リソースの場所は、インラインか、外部のカタログファイルか、 両方によって指定されます。 外部のカタログファイルを使うために、xml-commons解決ライブラリ("resolver.jar") をパスに設定しなければいけません。 外部のカタログファイルは、 プレーンテキストフォーマットまたは、 XMLフォーマットになります。 xml-commons解決ライブラリがクラスパス、外部のカタログファイル、 指定されたcatalogpathに見つからない場合、 無視され、警告が記録されます。この場合、どんな場合でも、 インラインエントリの処理は普通に進むでしょう。

現在、<dtd><entity>のみが、 インライン指定が可能です。 これらは、OASISカタログのエントリータイプの PUBLICURIそれぞれに、 だいたい一致します。

対照的に、外部のカタログファイルは、 OASIS仕様 で定義されたどんなエントリ型も使うことができます。

エンティティー/DTD/URI 解決アルゴリズム

XMLプロセッサーが、エンティティー、DTD、URIを見つけると、 XMLカタログは一致するものを見つけるため、エントリーのリストを検索します。 すなわち、解決するために、 それぞれのエントリーのpublicId属性と PublicIDやエンティティーのURIを一致させようとします。 一致するエントリーが見つかった場合、 XMLカタログは次のステップを実行します。

1. ファイルシステム検索

locationはファイルシステムの中で最初に検索されます。 locationが相対パスの場合、Antプロジェクトのbasedir属性が 基準ディレクトリとして使用されます。 locationが絶対パスで指定されていれば、そのまま使われます。 一度、取得した絶対パスに対して、それが有効でパス上に存在する読み込み可能なファイル かどうかチェックします。 そうであれば、それが使われ、そうでなければ、次のステップへ進みます。

2. クラスパス検索

locationは次にクラスパスの検索に使われます。 jarファイル(まれに気まぐれなzipファイル)が再読み込みされます。 クラスパス検索のために、locationは、そのまま使われます(baseは使われません)。 クラスローダーを使って、クラスパスからリソースをロードしようとします。 たとえば、hello.jarがクラスパスにあり、 foo/bar/blat.dtdを含んでいるならば、 locationfoo/bar/blat.dtdである エンティティーとして解決されます。 もちろんlocationblat.dtdの エンティティーは解決されません

3a. Apache xml-commons解決検索

次に何が起こるかは、クラスパス上のxml-commonsから解決ライブラリが利用可能かかどうかにに依存します。 もしそうなら、解決時にそれ以上の試みを見送ります。 解決ライブラリは、URLリライティングなどの、とても高度な機能サポートし、 外部のカタログファイル内で適当なエントリをすることによって、アクセスすることができます。 (XMLカタログは、 OASIS標準)内で定義されたすべてのエントリに対する、 インラインのサポートをまだ提供していません。)

3. URL空間検索

最後に、私たちは、locationの外のURLを使おうと試みます。 最初に、これはXMLカタログの目的を破ってしまうように見えます。 なぜ、インターネットに戻っていくのか? しかし実際、これは(ある意味)HTTPリダイレクトの実装や、 あるURLの他のURLへの代用として使われます。 マップしたURLはまた、ローカルのウェブサーバーを使って利用できるでしょう。 URLで有効で読み込み可能なリソースが解決すれば、それが使われます。 そうでなければ、あきらめます。 この場合、XMLプロセッサーは通常の解決アルゴリズムを実行します。 プロセッサーの設定によって、さらなる解決が失敗した場合、 致命的な(ビルドを終了させる)エラーとなるかもしれないし、ならないかもしれません。

XMLカタログ の属性

属性 説明 必須
id XMLカタログにとってユニークな名前。 他のXMLカタログから、XMLカタログの中身を参照するために使われます。 No
refid このXMLカタログで利用したい、 他のXMLカタログのid No

XMLカタログ のネストした要素

dtd/エンティティー

XMLカタログで使われるdtdentity要素は、 その構造の中で同じものです。

属性 説明 必須
publicId public識別子はdtdやエンティティーを 定義するときに使われます。 たとえば、 "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"。 Yes
location 指定されたpublic識別子に対して、ローカルで代わりに使われる場所。 これはファイル名、クラスパス上のリソース名、URLとして指定できます。 相対パスは、基準ディレクトリによって解決されます。 基準ディレクトリはデフォルトでAntプロジェクトのbasedirです。 Yes

クラスパス

エンティティ解決のために 使われるクラスパス。 ネストした<classpath>パス類似構造です。

カタログパス

ネストした catalogpath要素は、 検索のためのカタログファイルをリストする、パス類似構造です。 このパス内のすべてのファイルは、OASISカタログファイルは、 プレーンテキストフォーマットまたは、 XMLフォーマット のどちらかになると考えられます。 存在しないファイルを指定しているエントリは無視されます。 クラスパス内でxml-commonsが利用可能でない解決ライブラリのとき、 すべてのcatalogpathsは無視され、警告が記録されます。

ユーザーのホームディレクトリの中に、 ローカルに参照された1つのDTDを含むXMLカタログを準備します。

    <xmlcatalog>
        <dtd 
            publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
            location="/home/dion/downloads/docbook/docbookx.dtd"/>
    </xmlcatalog>

ファイルシステム(Antプロジェクトのbasedirからの相対パス)とクラスパス の両方から検索する、複数のDTDを含むXMLカタログを準備します。

    <xmlcatalog id="commonDTDs">
        <dtd 
            publicId="-//OASIS//DTD DocBook XML V4.1.2//EN"
            location="docbook/docbookx.dtd"/>
        <dtd 
            publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
            location="web-app_2_2.dtd"/>
    </xmlcatalog>

ネストしたXMLカタログと外部のカタログファイル、双方のフォーマットと同じように、 DTDとエンティティの組み合わせを含むXMLカタログを準備します。

    <xmlcatalog id="allcatalogs">
        <dtd 
            publicId="-//ArielPartners//DTD XML Article V1.0//EN"
            location="com/arielpartners/knowledgebase/dtd/article.dtd"/>
        <entity 
            publicId="LargeLogo"
            location="com/arielpartners/images/ariel-logo-large.gif"/>
        <xmlcatalog refid="commonDTDs"/>
            <catalogpath>
                <pathelement location="/etc/sgml/catalog"/>
                <fileset 
                    dir="/anetwork/drive"
                    includes="**/catalog"/>
                <fileset 
                    dir="/my/catalogs"
                    includes="**/catalog.xml"/>
            </catalogpath>
        </xmlcatalog>
    </xmlcatalog>

xsltタスクの中で、上のXMLカタログを参照します。

    <xslt basedir="${source.doc}"
           destdir="${dest.xdocs}"
           extension=".xml"
           style="${source.xsl.converter.docbook}"
           includes="**/*.xml"
           force="true">
        <xmlcatalog refid="allcatalogs"/>
    </xslt>

Copyright © 2002,2004 The Apache Software Foundation. All rights Reserved.

[訳注:これは宮本信二の訳を参考に、横田聡が翻訳しました。日本語訳に対するコメントがあれば report@jajakarta.orgに送ってください]