XMLCatalog

XMLカタログ

An XMLCatalog is a catalog of public resources such as DTDs or entities that are referenced in an XML document. Catalogs are typically used to make web references to resources point to a locally cached copy of the resource.

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

This allows the XML Parser, XSLT Processor or other consumer of XML documents to efficiently allow a local substitution for a resource available on the web.

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

This data type provides a catalog of resource locations based on the OASIS "Open Catalog" standard. The catalog entries are used both for Entity resolution and URI resolution, in accordance with the org.xml.sax.EntityResolver and javax.xml.transform.URIResolver interfaces as defined in the Java API for XML Processing (JAXP) Specification.

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

For example, in a web.xml file, the DTD is referenced as:

例えば、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">

The XML processor, without XMLCatalog support, would need to retrieve the DTD from the URL specified whenever validation of the document was required.

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

This can be very time consuming during the build process, especially where network throughput is limited. Alternatively, you can do the following:

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

  1. Copy web-app_2_2.dtd onto your local disk somewhere (either in the filesystem or even embedded inside a jar or zip file on the classpath).
  2. Create an <xmlcatalog> with a <dtd> element whose location attribute points to the file.
  3. Success! The XML processor will now use the local copy instead of calling out to the internet.
  1. web-app_2_2.dtdをローカルディスクのどこかへコピーします (ファイルシステムか、クラスパス上のjarやzipファイルに組み込みます)。
  2. そのファイルをlocation属性に指定した <dtd>要素を使って、 <xmlcatalog>を作成します。 。
  3. 成功すると、XMLプロセッサーはインターネットの代わりに今のローカルコピーを使います。

XMLCatalogs can appear inside tasks that support this feature or at the same level as target - i.e., as children of project for reuse across different tasks, e.g. XML Validation and XSLT Transformation. The XML Validate task uses XMLCatalogs for entity resolution. The XSLT Transformation task uses XMLCatalogs for both entity and URI resolution.

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

XMLCatalogs are specified as either a reference to another XMLCatalog, defined previously in a build file, or as a list of dtd or entity locations. A separate classpath for entity resolution may be specified inline via nested classpath elements; otherwise the system classpath is used for this as well.

XMLカタログは、他のXMLカタログへの参照として指定します。 ビルドファイルの中で前もって定義するか、 あるいは、dtdentityの場所のリストとして、指定します。 エンティティー解決のための区切られたクラスパスは、 ネストしたclasspath要素によって インラインで指定できます。 クラスパスを指定しない場合は、システムクラスパスが同様に使用されます。

XMLCatalogs can also be nested inside other XMLCatalogs. For example, a "superset" XMLCatalog could be made by including several nested XMLCatalogs that referred to other, previously defined XMLCatalogs.

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

Currently, only <dtd> and <entity> elements may be specified inline; these roughly correspond to OASIS catalog entry types PUBLIC and URI respectively.

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

Entity/DTD/URI Resolution Algorithm

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

When an entity, DTD, or URI is looked up by the XML processor, the XMLCatalog searches its list of entries to see if any match. That is, it attempts to match the publicId attribute of each entry with the PublicID or URI of the entity to be resolved. Assuming a matching entry is found, XMLCatalog then executes the following steps:

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

1. Filesystem lookup

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

The location is first looked up in the filesystem. If the location is a relative path, the ant project basedir attribute is used as the base directory. If the location specifies an absolute path, it is used as is. Once we have an absolute path in hand, we check to see if a valid and readable file exists at that path. If so, we are done. If not, we proceed to the next step.

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

2. Classpath lookup

2. クラスパス検索

The location is next looked up in the classpath. Recall that jar files are merely fancy zip files. For classpath lookup, the location is used as is (no base is prepended). We use a Classloader to attempt to load the resource from the classpath. For example, if hello.jar is in the classpath and it contains foo/bar/blat.dtd it will resolve an entity whose location is foo/bar/blat.dtd. Of course, it will not resolve an entity whose location is blat.dtd.

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

3. URL-space lookup

3. URL空間検索

Finally, we attempt to make a URL out of the location. At first this may seem like this would defeat the purpose of XMLCatalogs -- why go back out to the internet? But in fact, this can be used to (in a sense) implement HTTP redirects, substituting one URL for another. The mapped-to URL might also be served by a local web server. If the URL resolves to a valid and readable resource, we are done. Otherwise, we give up. In this case, the XML processor will perform its normal resolution algorithm. Depending on the processor configuration, further resolution failures may or may not result in fatal (i.e. build-ending) errors.

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

XMLCatalog attributes

XMLカタログ の属性

Attribute Description Required
id a unique name for an XMLCatalog, used for referencing the XMLCatalog's contents from another XMLCatalog No
refid the id of another XMLCatalog whose contents you would like to be used for this XMLCatalog No
属性 説明 必須
id XMLカタログにとってユニークな名前。 他のXMLカタログから、XMLカタログの中身を参照するために使われます。 No
refid このXMLカタログで利用したい、 他のXMLカタログのid No

XMLCatalog nested elements

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

dtd/entity

dtd/エンティティー

The dtd and entity elements used to specify XMLCatalogs are identical in their structure

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

Attribute Description Required
publicId The public identifier used when defining a dtd or entity, e.g. "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" Yes
location The location of the local replacement to be used for the public identifier specified. This may be specified as a file name, resource name found on the classpath, or a URL. Relative paths will be resolved according to the base, which by default is the Ant project basedir. Yes
属性 説明 必須
publicId public識別子はdtdやエンティティーを 定義するときに使われます。 たとえば、 "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"。 Yes
location 指定されたpublic識別子に対して、ローカルで代わりに使われる場所。 これはファイル名、クラスパス上のリソース名、URLとして指定できます。 相対パスは、基準ディレクトリによって解決されます。 基準ディレクトリはデフォルトでAntプロジェクトのbasedirです。 Yes

classpath

クラスパス

The classpath to use for entity resolution. The nested <classpath> is a path-like structure.

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

Examples

Set up an XMLCatalog with a single dtd referenced locally in a user's home directory:

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

    <xmlcatalog>

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

Set up an XMLCatalog with a multiple dtds to be found either in the filesystem (relative to the Ant project basedir) or in the classpath:

ファイルシステム(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>

Set up an XMLCatalog with a combination of DTDs and entities as well as a nested 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"/>
    </xmlcatalog>

To reference the above XMLCatalog in an xslt task:

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 Apache Software Foundation. All rights Reserved.

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