モジュール java.xml

パッケージ 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実装によって例外をスローできます。

導入されたバージョン:

1.5, 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を示している可能性があります。