モジュール java.xml
パッケージ 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を相互変換するためのアダプタも用意されています。

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

    • メソッドの詳細

      • 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()

      • setDTDHandler

        void setDTDHandler​(DTDHandler handler)
        アプリケーションにDTDイベント・ハンドラの登録を許可します。

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

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

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

      • setContentHandler

        void setContentHandler​(ContentHandler handler)
        アプリケーションにコンテンツ・イベント・ハンドラの登録を許可します。

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

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

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

      • setErrorHandler

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

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

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

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

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