XMLReader (Java 2 Platform SE 5.0)

概要

パッケージ

クラス

使用

階層ツリー

非推奨 API

索引

ヘルプ

Java^TM 2 Platform
Standard Ed. 5.0

前のクラス 次のクラス

フレームあり フレームなし

概要: 入れ子 | フィールド | コンストラクタ | メソッド

詳細: フィールド | コンストラクタ | メソッド

org.xml.sax
インタフェース XMLReader

既知のサブインタフェースの一覧:: XMLFilter

既知の実装クラスの一覧:: ParserAdapter, XMLFilterImpl

public interface XMLReader

コールバックを使用して XML 文書を読み取るためのインタフェースです。

このモジュールは、ソースコード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。詳細は、http://www.saxproject.org を参照してください。

注: このインタフェースは、その名前にもかかわらず、標準 Java Reader インタフェースを拡張しません。これは、XML の読み取りと文字データの読み取りが根本的に異なっているからです。

XMLReader は、XML パーサの SAX2 ドライバが実装しなければならない必須インタフェースです。アプリケーションは、パーサの機能やプロパティの設定および照会、文書処理のためのイベントハンドラの登録、文書の構文解析の開始にこのインタフェースを使用します。

すべての SAX インタフェースは同期しているものと見なされます。parse メソッドは、構文解析が完了するまで終了しません。リーダは、イベントハンドラのコールバックが返されるのを待ってから、次のイベントを報告します。

このインタフェースは、現在は非推奨に指定されている SAX 1.0 の Parser インタフェースに代わるインタフェースです。XMLReader インタフェースは、古い Parser インタフェースや一部のマイナーなインタフェースの機能に加えて、2 つの重要な拡張機能を備えています。

機能やプロパティを照会および設定するための標準的な方法
高度な XML 標準で必要とされることが多い名前空間のサポート

SAX1 の Parser と SAX2 の XMLReader を相互変換するためのアダプタも用意されています。

導入されたバージョン:: SAX 2.0
関連項目:: XMLFilter, ParserAdapter, XMLReaderAdapter

メソッドの概要
`ContentHandler`	`getContentHandler()` 現在のコンテンツハンドラを返します。
`DTDHandler`	`getDTDHandler()` 現在の DTD ハンドラを返します。
`EntityResolver`	`getEntityResolver()` 現在のエンティティリゾルバを返します。
`ErrorHandler`	`getErrorHandler()` 現在のエラーハンドラを返します。
`boolean`	`getFeature(String name)` 機能フラグの値を検索します。
`Object`	`getProperty(String name)` プロパティ値を検索します。
`void`	`parse(InputSource input)` XML 文書を構文解析します。
`void`	`parse(String systemId)` システム識別子 (URI) から XML 文書を構文解析します。
`void`	`setContentHandler(ContentHandler handler)` アプリケーションにコンテンツイベントハンドラの登録を許可します。
`void`	`setDTDHandler(DTDHandler handler)` アプリケーションに DTD イベントハンドラの登録を許可します。
`void`	`setEntityResolver(EntityResolver resolver)` アプリケーションにエンティティリゾルバの登録を許可します。
`void`	`setErrorHandler(ErrorHandler handler)` アプリケーションにエラーイベントハンドラの登録を許可します。
`void`	`setFeature(String name, boolean value)` 機能フラグの値を設定します。
`void`	`setProperty(String name, Object value)` プロパティ値を設定します。

メソッドの詳細

getFeature

boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

機能フラグの値を検索します。

機能名は完全修飾 URI です。XMLReader は機能名を認識することはできますが、同時にその値を返すことはできません。機能の値によっては、構文解析の実行前、実行中、実行後などの特定のコンテキストでのみ使用可能な場合があります。また、プログラムではアクセスできない機能値もあります。SAX1 Parser のアダプタの場合、基本となるパーサが検証を実行しているかどうかや、外部エンティティを拡張しているかどうかなどを表示する方法は実装に依存しません。

すべての XMLReader は、http://xml.org/sax/features/namespaces と http://xml.org/sax/features/namespace-prefixes の機能名を認識する必要があります。

一般的な使用方法は次のとおりです。


 XMLReader r = new MySAXDriver();

                         // try to activate validation
 try {
   r.setFeature("http://xml.org/sax/features/validation", true);
 } catch (SAXException e) {
   System.err.println("Cannot activate validation."); 
 }

                         // register event handlers
 r.setContentHandler(new MyContentHandler());
 r.setErrorHandler(new MyErrorHandler());

                         // parse the first document
 try {
   r.parse("http://www.foo.com/mydoc.xml");
 } catch (IOException e) {
   System.err.println("I/O exception reading XML document");
 } catch (SAXException e) {
   System.err.println("XML exception reading document.");
 }

独自の URI に基づいて作成された名前を使用して、実装者が独自の機能を作成することもできます (推奨)。

パラメータ:: name - 機能名。完全修飾 URI で表される
戻り値:: 機能の現在の値 (true または false)
例外:: SAXNotRecognizedException - 機能の値を割り当て、または取得できない場合; SAXNotSupportedException - XMLReader が機能名を認識するだけで、現時点ではその値を判断できない場合
関連項目:: setFeature(java.lang.String, boolean)

setFeature

void setFeature(String name,
                boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException

機能フラグの値を設定します。

機能名は完全修飾 URI です。XMLReader は機能の値を表示できますが、現在の値を変更することはできません。機能の値によっては、構文解析の実行前、実行中、実行後などの特定のコンテキストでのみ不変または可変である場合があります。

すべての XMLReader で、http://xml.org/sax/features/namespaces と http://xml.org/sax/features/namespace-prefixes が false に設定されている必要があります。

パラメータ:: name - 機能名。完全修飾 URI で表される; value - 機能の要求された値 (true または false)
例外:: SAXNotRecognizedException - 機能の値を割り当て、または取得できない場合; SAXNotSupportedException - XMLReader が機能名を認識するだけで要求された値を設定できない場合
関連項目:: getFeature(java.lang.String)

getProperty

Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

プロパティ値を検索します。

プロパティ名は完全修飾 URI です。XMLReader はプロパティ名を認識できますが、一時的にその値を返すことはできません。プロパティの値によっては、構文解析の実行前、実行中、実行後などの特定のコンテキストでしか使用できない場合があります。

SAX2 には初期コアセットが文書化されていますが、XMLReader は特定のプロパティ名を認識できなくてもかまいません。

独自の URI に基づいて作成された名前を使用して、実装者が独自のプロパティを作成することもできます (推奨)。

パラメータ:: name - プロパティ名。完全修飾 URI で表される
戻り値:: 現在のプロパティ値
例外:: SAXNotRecognizedException - プロパティの値を割り当て、または取得できない場合; SAXNotSupportedException - XMLReader がプロパティ名を認識するだけで、現時点ではその値を判断できない場合
関連項目:: setProperty(java.lang.String, java.lang.Object)

setProperty

void setProperty(String name,
                 Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException

プロパティ値を設定します。

プロパティ名は完全修飾 URI です。XMLReader はプロパティ名を認識できますが、現在の値を変更することはできません。プロパティの値によっては、構文解析の実行前、実行中、実行後などの特定のコンテキストでのみ不変または可変である場合があります。

コアセットは SAX2 によって定義されていますが、XMLReader は特定のプロパティ名を認識できなくてもかまいません。

このメソッドは、拡張ハンドラの設定に使用する標準機構でもあります。

パラメータ:: name - プロパティ名。完全修飾 URI で表される; value - 要求されたプロパティ値
例外:: SAXNotRecognizedException - プロパティの値を割り当て、または取得できない場合; SAXNotSupportedException - XMLReader がプロパティ名を認識するだけで要求された値を設定できない場合

setEntityResolver

void setEntityResolver(EntityResolver resolver)

アプリケーションにエンティティリゾルバの登録を許可します。

アプリケーションがエンティティリゾルバを登録しないと、XMLReader がデフォルトの解決を独自に行います。

アプリケーションは、構文解析中も新しいエンティティリゾルバを登録できます。新しいリゾルバが登録され次第、SAX パーサはただちにこのリゾルバの使用を開始する必要があります。

パラメータ:: resolver - エンティティリゾルバ
関連項目:: getEntityResolver()

getEntityResolver

EntityResolver getEntityResolver()

現在のエンティティリゾルバを返します。

戻り値:: 現在のエンティティリゾルバ。登録されていない場合は null
関連項目:: setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

void setDTDHandler(DTDHandler handler)

アプリケーションに DTD イベントハンドラの登録を許可します。

アプリケーションが DTD ハンドラを登録しないと、SAX パーサから報告されるすべての DTD イベントは通知なく無視されます。

アプリケーションは、構文解析中も新しいハンドラを登録できます。新しいハンドラが登録され次第、SAX パーサはただちにこのハンドラの使用を開始する必要があります。

パラメータ:: handler - DTD ハンドラ
関連項目:: getDTDHandler()

getDTDHandler

DTDHandler getDTDHandler()

現在の DTD ハンドラを返します。

戻り値:: 現在の DTD ハンドラ。登録されていない場合は null
関連項目:: setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

void setContentHandler(ContentHandler handler)

アプリケーションにコンテンツイベントハンドラの登録を許可します。

アプリケーションがコンテンツハンドラを登録しないと、SAX パーサから報告されるすべてのコンテンツイベントは通知なく無視されます。

パラメータ:: handler - コンテンツハンドラ
関連項目:: getContentHandler()

getContentHandler

ContentHandler getContentHandler()

現在のコンテンツハンドラを返します。

戻り値:: 現在のコンテンツハンドラ。登録されていない場合は null
関連項目:: setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

void setErrorHandler(ErrorHandler handler)

アプリケーションにエラーイベントハンドラの登録を許可します。

アプリケーションがエラーハンドラを登録しないと、SAX パーサから報告されるすべてのエラーイベントは通知なく無視されます。ただし、通常処理は続行できます。予想外のバグを回避するため、すべての SAX アプリケーションにエラーハンドラを実装することを強くお勧めします。

パラメータ:: handler - エラーハンドラ
関連項目:: getErrorHandler()

getErrorHandler

ErrorHandler getErrorHandler()

現在のエラーハンドラを返します。

戻り値:: 現在のエラーハンドラ。登録されていない場合は null
関連項目:: setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(InputSource input)
           throws IOException,
                  SAXException

XML 文書を構文解析します。

アプリケーションは、このメソッドを使用して、有効な任意の入力ソース (文字ストリーム、バイトストリーム、または URI) から XML 文書の構文解析を開始するように XML リーダに指示を送ります。

構文解析中はアプリケーションからこのメソッドを呼び出すことはできません。アプリケーションは、入れ子になっているそれぞれの XML 文書に対して代わりに新しい XMLReader を作成する必要があります。構文解析が終了するとアプリケーションは同じ XMLReader オブジェクトを再利用しますが、別の入力ソースでの再利用も可能です。機能フラグやプロパティに設定されたハンドラバインディングや値などの XMLReader オブジェクトの構成は、構成のその面の定義が他の動作を明示的に指定しないかぎり、構文解析が終了しても変更されません。これには、構文解析されている文書の特性を公開する機能フラグやプロパティがあります。

構文解析中、XMLReader は登録済みのイベントハンドラを介して XML 文書に関する情報を提供します。

このメソッドは同期メソッドであり、構文解析が終了するまでは終了しません。クライアントアプリケーションから構文解析を早期に終了する要求があった場合は例外をスローします。

パラメータ:: input - XML 文書のトップレベルの入力ソースです。
例外:: SAXException - SAX 例外。ほかの例外をラップしている可能性がある; IOException - パーサからの IO 例外。通常、アプリケーションが提供するバイトストリームまたは文字ストリームからの例外
関連項目:: InputSource, parse(java.lang.String), setEntityResolver(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setContentHandler(org.xml.sax.ContentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

parse

void parse(String systemId)
           throws IOException,
                  SAXException

システム識別子 (URI) から XML 文書を構文解析します。

このメソッドを使用すると、システム識別子から簡単に文書を読み取ることができます。次の指定でも同じことができます。


parse(new InputSource(systemId));

システム識別子が URL の場合、アプリケーションはこれをパーサに渡す前に完全に解決する必要があります。

パラメータ:: systemId - システム識別子 (URI)
例外:: SAXException - SAX 例外。ほかの例外をラップしている可能性がある; IOException - パーサからの IO 例外。通常、アプリケーションが提供するバイトストリームまたは文字ストリームからの例外
関連項目:: parse(org.xml.sax.InputSource)