JavaTM Platform
Standard Ed. 6

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 つの重要な拡張機能を備えています。

  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

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 パーサーから報告されるすべてのコンテンツイベントは通知なく無視されます。

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

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

getContentHandler

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

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

setErrorHandler

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

アプリケーションがエラーハンドラを登録しないと、SAX パーサーから報告されるすべてのエラーイベントは通知なく無視されます。 ただし、通常処理は続行できます。予想外のバグを回避するため、すべての 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)

JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。