org.xml.sax.ext
インタフェース EntityResolver2

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

EntityResolver

既知の実装クラスの一覧:

DefaultHandler2

public interface EntityResolver2
extends EntityResolver

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

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

外部実体のためにこのインタフェースを定義するようにカスタマイズする必要がある場合、SAX アプリケーションは「true」(機能が認識された場合のデフォルト値) に設定された「http://xml.org/sax/features/use-entity-resolver2」機能フラグを持つ 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。SAX2 パーサによって呼び出される場合は null ではなく、宣言された実体と外部サブセットだけが、そうしたパーサによって解決される

戻り値:

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

例外:

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

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