org.xml.sax.ext

インタフェース EntityResolver2

すべてのスーパーインタフェース:

EntityResolver

既知のすべての実装クラス:

DefaultHandler2

public interface EntityResolver2
extends EntityResolver

外部エンティティー参照を入力ソースにマッピングしたり、不足する外部サブセットを提供したりする拡張インタフェースです。XMLReader.setEntityResolver() メソッドを使用してパーサーにこのインタフェースの実装を提供します。パーサーがこのインタフェースのメソッドを使用する場合、古い SAX 1.0 EntityResolver.resolveEntity() メソッドの代わりに、このインタフェースの EntityResolver2.resolveEntity() メソッドを使用します。

このモジュールは、ソースコード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。

SAX アプリケーションは、このインタフェースによって定義される外部エンティティーのカスタム処理を必要とする場合、http://xml.org/sax/features/use-entity-resolver2 機能フラグが true (機能が認識された場合のデフォルト値) に設定された XMLReader を使用する必要があります。そのフラグが認識されない場合やその値が false の場合、またはリゾルバがこのインタフェースを実装しない場合には、EntityResolver メソッドだけを使用します。

このインタフェースはエンティティー解決を変更する 3 種類のアプリケーションをサポートします。Old Style アプリケーションはこのインタフェースについては認識せず、EntityResolver を提供します。Transitional Mode は EntityResolver2 を提供し、EntityResolver2 をサポートするすべてのシステム (パーサーまたはその他のツール) でそのメソッドの利点が自動的に得られます (多相性のため)。Old Style アプリケーションも Transitional Mode アプリケーションも、任意の SAX2 パーサーで動作します。New style アプリケーションは、この特定の機能をサポートしている SAX2 パーサー以外では動作しません。元の SAX 1.0 スタイルエンティティー解決メソッドが呼び出された場合、これらのアプリケーションは機能フラグが「true」の値を持つように要求し、提供する EntityResolver2 実装によって例外をスローできます。

導入されたバージョン:

SAX 2.0 (extensions 1.1 alpha)

関連項目:

XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

メソッドのサマリー

メソッド

修飾子と型	メソッドと説明
InputSource	getExternalSubset(String name, String baseURI) アプリケーションは、明確に定義していない文書の外部サブセットを提供できます。
InputSource	resolveEntity(String name, String publicId, String baseURI, String systemId) アプリケーションは外部エンティティー参照を入力ソースへマッピングするか、一般的な URI 解決を使用するようパーサーに通知できます。

インタフェース org.xml.sax.EntityResolver から継承されたメソッド

resolveEntity

メソッドの詳細

getExternalSubset

InputSource getExternalSubset(String name,
                            String baseURI)
                              throws SAXException,
                                     IOException

アプリケーションは、明確に定義していない文書の外部サブセットを提供できます。外部サブセットを省略する DOCTYPE 宣言付きの文書は、検証、エンティティーの処理、属性の処理 (正規化、デフォルト設定、ID を含む型をレポートする) に使用できる宣言を増やすことができます。この拡張は startDTD() メソッドを通して、すでに文書には外部サブセットが含まれていたかのように報告されます。このコールバックは、すべての内部サブセットデータやエラーが報告される前に行われます。

また、このメソッドは DOCTYPE 宣言を持たない文書にも使用できます。ルート要素が検出されても DOCTYPE 宣言が見つからなかった場合にこのメソッドが呼び出されます。外部サブセットの値を返す場合、このルート要素はルート要素として宣言され、無効になる文書の最初に DOCTYPE 宣言をつなぐ効果をもたらします。そのパーサーコールバックのシーケンスは論理的には次のケースと似ています。

 ... comments and PIs from the prolog (as usual)
 startDTD ("rootName", source.getPublicId (), source.getSystemId ());
 startEntity ("[dtd]");
 ... declarations, comments, and PIs from the external subset
 endEntity ("[dtd]");
 endDTD ();
 ... then the rest of the document (as usual)
 startElement (..., "rootName", ...);
 

InputSource ではこれ以上の解決は取得されません。このメソッドの実装では resolveEntity() を呼び出して DTD エンティティーのローカルキャッシュを使用するなどの利点を得ることができます。また、妥当性を検証せず、外部パラメータエンティティーを含んでいないプロセッサではこのメソッドを使用できません。

外部エンティティーに対して好ましくないネットワークアクセスを常に要求する XML プロセッサと互換性がある場合、このメソッドに使用するとデータの検証も容易になります。また、ほかの理由には DTD 以外のポリシーをインポートします。妥当性を検証できない原因には、文書に DTD を含めるよう要求します。これによって属性がむらなく処理されます。たとえば、XPath プロセッサは、広く使用されている参照の型を処理する前に型「ID」を持つ属性を認識する必要があります。

警告: 外部サブセットを返すと入力文書が変更されます。一般のエンティティーに定義を与えることによって不正な文書を整形できます。

パラメータ:

name - 文書のルート要素の識別。利用可能な DOCTYPE 宣言または実際のルート要素からの名前。

baseURI - 文書のベース URI。外部サブセットを選択する追加ヒントとして機能する。XMLReader に InputSource しか提供されなかったために null となる場合を除き、常に絶対 URI である。

戻り値:

パーサーによって使用される新しい外部サブセットを記述する InputSource オブジェクト。外部サブセットが提供されない場合は null が示される。

例外:

SAXException - 任意の SAX 例外。ほかの例外をラップしている可能性があります。

IOException - 新しい InputStream や Reader の作成失敗、または不正な URL を示している可能性があります。

resolveEntity

InputSource resolveEntity(String name,
                        String publicId,
                        String baseURI,
                        String systemId)
                          throws SAXException,
                                 IOException

アプリケーションは外部エンティティー参照を入力ソースへマッピングするか、一般的な URI 解決を使用するようパーサーに通知できます。このメソッドは、正しく宣言された外部エンティティーだけに要求されます。このメソッドは EntityResolver インタフェースに比べて柔軟性があり、OASIS XML Catalogs 仕様で定義されているようなより複雑なカタログスキームの実装をサポートします。

このリゾルバメソッドを使用するように設定されたパーサーは、リゾルバメソッドを呼び出して XML テキストの参照によって含まれている外部エンティティーに使用する入力ソースを決定します。その場合、文書エンティティーと getExternalSubset() によって返された外部エンティティーは除外されます。妥当性を検証できないプロセッサが機能フラグを使用してエンティティー (パラメータエンティティーまたは一般エンティティー) のクラスを含めないように設定されていると、このメソッドはそれらのエンティティーでは呼び出されません。

ここで使用されるエンティティー命名スキームは、LexicalHandler または ContentHandler.skippedEntity() メソッドで使用されるものと同じです。

パラメータ:

name - 解決される外部エンティティーの識別。外部サブセットの「[dtd]」やパラメータエンティティーを示す「%」で開始される名前、またはそれ以外の一般エンティティーの名前。SAX2 パーサーによって呼び出される場合 null にはなりません。

publicId - 参照される外部エンティティーの公開識別子 (XML 仕様で要求されるように正規化されている)。提供されなかった場合は null。

baseURI - 相対的な systemID を解釈するときに基準にする URI。XMLReader は InputSource に指定された可能性があるので、null でないかぎり常に絶対 URI。この URI は、関連する宣言を開始する「<」に関連付けられている XML 仕様によって定義されます。

systemId - 参照される外部エンティティーのシステム識別子。相対 URI または絶対 URI。SAX2 パーサーによって呼び出される場合 null にはなりません。宣言されたエンティティーと外部サブセットだけが、そうしたパーサーによって解決されます。

戻り値:

パーサーによって使用される新しい入力ソースを記述する InputSource オブジェクト。null を返すことによって、基底 URI に対するシステム ID を解決し、結果として得られる URI につなげるようにパーサーに指示する。

例外:

SAXException - 任意の SAX 例外。ほかの例外をラップしている可能性があります。

IOException - 新しい InputStream や Reader の作成失敗、または不正な URL を示している可能性があります。