XMLCatalog

XMLCatalogは、XMLドキュメントで参照されるDTDやエンティティなどのパブリックリソースのカタログです。カタログは通常、Web上のリソースへの参照を、リソースのローカルにキャッシュされたコピーを指すようにするために使用されます。

これにより、XMLパーサー、XSLTプロセッサ、またはXMLドキュメントの他のコンシューマーは、Web上で利用可能なリソースを効率的にローカルに代替することができます。

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

このデータ型は、OASIS XML Catalog標準に基づいたリソースロケーションのカタログを提供します。カタログエントリは、Java API for XML Processing (JAXP) 仕様で定義されているorg.xml.sax.EntityResolverおよびjavax.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プロセッサは、XMLCatalogのサポートがない場合、ドキュメントの検証が必要になるたびに、指定されたURLからDTDを取得する必要があります。

これは、特にネットワークスループットが制限されている場合、ビルドプロセス中に非常に時間がかかる可能性があります。代わりに、次のようにすることができます。

  1. web-app_2_2.dtdをローカルディスクのどこかにコピーします（ファイルシステム内、またはクラスパス上のjarまたはzipファイル内に埋め込まれている場合も同様です）。
  2. location属性がそのファイルを指す<dtd>要素を持つ<xmlcatalog>を作成します。
  3. 成功です！XMLプロセッサは、インターネットにアクセスする代わりに、ローカルコピーを使用するようになります。

XMLCatalogは、この機能をサポートするタスク内、またはtargetと同じレベル（つまり、XML検証やXSLT変換など、異なるタスク間で再利用するためにprojectの子として）で表示できます。XML検証タスクは、エンティティ解決にXMLCatalogを使用します。XSLT変換タスクは、エンティティ解決とURI解決の両方にXMLCatalogを使用します。

XMLCatalogは、ビルドファイルで以前に定義された別のXMLCatalogへの参照として、またはdtdまたはentityのロケーションのリストとして指定されます。さらに、ネストされたcatalogpathで外部カタログファイルを指定できますが、xml-commonsのresolverライブラリがシステムのクラスパスで使用可能でない限り、無視されます。resolver 1.0のリリース後のresolverコードにおける後方互換性のない変更のため、Antはresolver 1.1以降のみをサポートします。 エンティティ解決用の個別のクラスパスは、ネストされたclasspath要素を介してインラインで指定できます。それ以外の場合は、システムのクラスパスもこれに使用されます。

XMLCatalogは、他のXMLCatalogの内部にネストすることもできます。たとえば、他の、以前に定義されたXMLCatalogを参照する複数のネストされたXMLCatalogを含めることで、「スーパーセット」XMLCatalogを作成できます。

リソースロケーションは、インラインまたは外部カタログファイル、あるいはその両方で指定できます。外部カタログファイルを使用するには、xml-commons resolverライブラリ（resolver.jar）がパスにある必要があります。外部カタログファイルは、プレーンテキスト形式またはXML形式のいずれかです。xml-commons resolverライブラリがクラスパスに見つからない場合、catalogpathで指定された外部カタログファイルは無視され、警告がログに記録されます。ただし、この場合でも、インラインエントリの処理は正常に続行されます。

現在、インラインで指定できるのは<dtd>要素と<entity>要素のみです。これらは、OASISカタログエントリタイプのPUBLICとURIにほぼ対応します。対照的に、外部カタログファイルは、OASIS仕様で定義されている任意のエントリタイプを使用できます。

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

エンティティ、DTD、またはURIがXMLプロセッサによって検索されるとき、XMLCatalogはそのエントリのリストを検索して、一致するものがあるかどうかを確認します。つまり、解決するエンティティのPublicIDまたはURIと各エントリのpublicId属性を照合しようとします。一致するエントリが見つかったと仮定して、XMLCatalogは次の手順を実行します。

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

locationは、最初にファイルシステムで検索されます。locationが相対パスである場合、Antプロジェクトのbasedir属性がベースディレクトリとして使用されます。locationが絶対パスを指定している場合は、そのまま使用されます。絶対パスが手に入ったら、そのパスに有効で読み取り可能なファイルが存在するかどうかを確認します。存在する場合は完了です。存在しない場合は、次のステップに進みます。

2. クラスパス検索

次に、locationがクラスパスで検索されます。jarファイルは単なる高度なzipファイルであることを思い出してください。クラスパス検索の場合、locationはそのまま使用されます（ベースは先頭に追加されません）。Classloaderを使用して、クラスパスからリソースをロードしようとします。たとえば、hello.jarがクラスパスにあり、foo/bar/blat.dtdが含まれている場合、locationがfoo/bar/blat.dtdであるエンティティを解決します。もちろん、locationがblat.dtdであるエンティティは解決しません。

3a. Apache xml-commons resolver検索

次に何が起こるかは、xml-commonsのresolverライブラリがクラスパスで使用可能かどうかによって異なります。使用可能な場合は、それ以降の解決の試行をすべてそれに委ねます。resolverライブラリは、URL書き換えなどの非常に洗練された機能をサポートしており、外部カタログファイルに適切なエントリを作成することでアクセスできます（XMLCatalogは、OASIS標準で定義されているすべてのエントリのインラインサポートをまだ提供していません）。

3. URL空間検索

最後に、locationからURLを作成しようとします。最初は、これはXMLCatalogの目的を無効にするように思えるかもしれません。なぜインターネットに戻るのか？しかし実際には、これは（ある意味で）HTTPリダイレクトを実装するために使用でき、あるURLを別のURLに置き換えることができます。マップ先のURLは、ローカルWebサーバーによって提供される場合もあります。URLが有効で読み取り可能なリソースに解決される場合は完了です。それ以外の場合は諦めます。この場合、XMLプロセッサは通常の解決アルゴリズムを実行します。プロセッサの構成によっては、それ以上の解決の失敗が致命的な（つまり、ビルドを終了させる）エラーになる場合もあれば、そうでない場合もあります。

XMLCatalog属性

属性 説明 必須
id XMLCatalogの一意の名前。別のXMLCatalogからXMLCatalogの内容を参照するために使用されます いいえ
refid このXMLCatalogに使用したい内容を持つ別のXMLCatalogのid いいえ

XMLCatalogのネストされた要素

dtd/entity

XMLCatalogを指定するために使用されるdtd要素とentity要素は、構造が同一です

属性 説明 必須
publicId DTDまたはエンティティを定義するときに使用されるパブリック識別子（例："-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"） はい
location 指定されたパブリック識別子に使用するローカル置換の場所。これは、ファイル名、クラスパスで見つかったリソース名、またはURLとして指定できます。相対パスは、デフォルトではAntプロジェクトのbasedirであるベースに従って解決されます。 はい

classpath

エンティティ解決に使用するクラスパス。ネストされた<classpath>はパスのような構造です。

catalogpath

ネストされたcatalogpath要素は、検索するカタログファイルのリストであるパスのような構造です。このパス内のすべてのファイルは、プレーンテキスト形式またはXML形式のいずれかのOASISカタログファイルであると想定されます。存在しないファイルを指定するエントリは無視されます。xml-commonsのresolverライブラリがクラスパスで使用可能でない場合、すべてのcatalogpathは無視され、警告がログに記録されます。

例

ユーザーのホームディレクトリでローカルに参照される単一のDTDを持つXMLCatalogを設定します。

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

ファイルシステム（Antプロジェクトのbasedirに対して相対的）またはクラスパスのいずれかで見つかる複数のDTDを持つXMLCatalogを設定します。

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

DTDとエンティティの組み合わせ、およびネストされたXMLCatalogと両方の形式の外部カタログファイルを持つXMLCatalogを設定します。

<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タスクで上記のXMLCatalogを参照するには

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