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

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

XMLFilter

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

ParserAdapter, XMLFilterImpl

public interface XMLReader

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

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

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

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

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

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

1. 機能やプロパティを照会および設定するための標準的な方法
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

public boolean getFeature(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

機能の値を検索します。

機能名は完全修飾 URI で表されます。XMLReader は機能名を認識しますが、その値を返すことはできません。このことは、特に SAX1 の Parser 用アダプタに当てはまります。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 - XMLReader が機能名を認識しない場合

SAXNotSupportedException - XMLReader が機能名を認識するだけで、現時点ではその値を判断できない場合

関連項目:

setFeature(java.lang.String, boolean)

setFeature

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

機能の状態を設定します。

機能名は完全修飾 URI で表されます。XMLReader は機能名を認識しますが、その値を設定することはできません。このことは、特に SAX1 の Parser 用アダプタに当てはまります。たとえば、SAX1 の Parser 用アダプタは、パーサに妥当性を検証を実行させるかどうかを決定することができません。

すべての XMLReader は、http://xml.org/sax/features/namespaces と http://xml.org/sax/features/namespace-prefixes を false に設定できなければなりません。

一部の機能の値は、特定の状況 (構文解析前、構文解析中、構文解析後など) でだけ不変または可変になります。

パラメータ:

name - 機能名。完全修飾 URI で表される

例外:

SAXNotRecognizedException - XMLReader が機能名を認識しない場合

SAXNotSupportedException - XMLReader が機能名を認識するだけで要求された値を設定できない場合

関連項目:

getFeature(java.lang.String)

getProperty

public Object getProperty(String name)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException

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

プロパティ名は完全修飾 URI で表されます。XMLReader はプロパティを認識するだけで、その状態を返すことはできません。このことは、特に SAX1 の Parser 用アダプタに当てはまります。

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

一部のプロパティ値は、特定の状況 (構文解析前、構文解析中、構文解析後など) でだけ使用可能です。

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

パラメータ:

name - プロパティ名。完全修飾 URI で表される

戻り値:

現在のプロパティ値

例外:

SAXNotRecognizedException - XMLReader がプロパティ名を認識しない場合

SAXNotSupportedException - XMLReader がプロパティ名を認識するだけで、現時点ではその値を判断できない場合

関連項目:

setProperty(java.lang.String, java.lang.Object)

setProperty

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

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

プロパティ名は完全修飾 URI で表されます。XMLReader はプロパティを認識するだけで、その値を設定することはできません。このことは、特に SAX1 の Parser 用アダプタに当てはまります。

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

一部のプロパティ値は、特定の状況 (構文解析前、構文解析中、構文解析後など) でだけ不変または可変になります。

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

パラメータ:

name - プロパティ名。完全修飾 URI で表される

例外:

SAXNotRecognizedException - XMLReader がプロパティ名を認識しない場合

SAXNotSupportedException - XMLReader がプロパティ名を認識するだけで要求された値を設定できない場合

setEntityResolver

public void setEntityResolver(EntityResolver resolver)

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

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

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

パラメータ:

resolver - エンティティリゾルバ

例外:

NullPointerException - リゾルバ引数が null の場合

関連項目:

getEntityResolver()

getEntityResolver

public EntityResolver getEntityResolver()

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

戻り値:

現在のエンティティリゾルバ。登録されていない場合は null

関連項目:

setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

public void setDTDHandler(DTDHandler handler)

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

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

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

パラメータ:

handler - DTD ハンドラ

例外:

NullPointerException - ハンドラ引数が null の場合

関連項目:

getDTDHandler()

getDTDHandler

public DTDHandler getDTDHandler()

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

戻り値:

現在の DTD ハンドラ。登録されていない場合は null

関連項目:

setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

public void setContentHandler(ContentHandler handler)

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

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

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

パラメータ:

handler - コンテンツハンドラ

例外:

NullPointerException - ハンドラ引数が null の場合

関連項目:

getContentHandler()

getContentHandler

public ContentHandler getContentHandler()

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

戻り値:

現在のコンテンツハンドラ。登録されていない場合は null

関連項目:

setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

public void setErrorHandler(ErrorHandler handler)

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

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

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

パラメータ:

handler - エラーハンドラ

例外:

NullPointerException - ハンドラ引数が null の場合

関連項目:

getErrorHandler()

getErrorHandler

public ErrorHandler getErrorHandler()

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

戻り値:

現在のエラーハンドラ。登録されていない場合は null

関連項目:

setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(InputSource input)
           throws IOException,
                  SAXException

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

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

構文解析中は、アプリケーションからこのメソッドを呼び出すことはできません。入れ子になっている XML 文書 1 つ 1 つに対して新しい XML リーダを作成する必要があります。構文解析が完了したら、同じ XMLReader オブジェクトを再利用できます。別の入力ソースでの再利用も可能です。

構文解析中、XMLReader は登録済みのイベントハンドラを介して 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

public 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)