モジュール java.xml
パッケージ org.xml.sax

インタフェースDocumentHandler

  • 既知のすべての実装クラス:
    HandlerBase, ParserAdapter
    非推奨。 
    このインタフェースは、名前空間サポートを含むSAX2 ContentHandlerインタフェースで置き換えられています。

    @Deprecated(since="1.5")
public interface DocumentHandler
    一般的な文書イベントの通知を受け取ります。
    このモジュールは、ソース・コード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。 詳細については、http://www.saxproject.orgを参照してください。

    これはSAX1のメインのイベント処理インタフェースでしたが、SAX2では、名前空間機能とスキップされたエンティティの報告機能をサポートするContentHandlerで置き換えられました。 このインタフェースは、SAX1のレガシー・アプリケーションのサポート専用としてSAX2に含められています。

    このインタフェース内のイベントの順序は、文書自体に含まれる情報の順序をミラー化したものであり、非常に重要です。 たとえば、ある要素の全コンテンツ(文字データ、処理命令、サブ要素など)は、startElementイベントとこれに対応するendElementイベントの間に順番に並べられます。

    アプリケーションの作成者は、インタフェース全体を実装する必要がない場合は、デフォルト機能を実装するHandlerBaseからクラスを派生できます。パーサーの作成者は、HandlerBaseをインスタンス化してデフォルト・ハンドラを取得できます。 アプリケーションは、Parserが提供するLocatorインタフェースを使用して、setDocumentLocatorメソッドから任意の文書イベントの位置を突き止めることができます。

    導入されたバージョン:
    1.4, SAX 1.0
    関連項目:
    Parser.setDocumentHandler(org.xml.sax.DocumentHandler), Locator, HandlerBase

    • メソッドの詳細

      • setDocumentLocator

        void setDocumentLocator​(Locator locator)
        非推奨。 
        SAX文書イベントの発生元を特定するオブジェクトを受け取ります。

        ロケータが必要な場合は、必須条件ではありませんが、SAXパーサーを使用することを強くお勧めします。SAXパーサーは、DocumentHandlerインタフェース内のどのメソッドよりも先にこのメソッドを呼び出し、アプリケーションにロケータを提供します。

        アプリケーションは、ロケータを利用して、パーサーがエラーを報告しない場合でも文書関連イベントの終了位置を特定できます。 通常、アプリケーションはこの情報を使って固有のエラー(文字コンテンツがアプリケーションの機能規則に沿っていないなど)を報告します。 一般に、ロケータから返される情報は不十分であり、検索エンジンでの使用に適していません。

        ロケータが正しい情報を返すのは、このインタフェース内でイベント呼出しが行われている間だけです。 それ以外のとき、アプリケーションでロケータの情報を利用するべきではありません。

        パラメータ:
        locator - SAX文書イベントの位置を返すオブジェクト。
        関連項目:
        Locator

      • startDocument

        void startDocument​()
            throws SAXException
        非推奨。 
        文書の開始通知を受け取ります。

        SAXパーサーは、このメソッドをこのインタフェース内またはDTDHandler内のどのメソッドよりも先に、1回だけ呼び出します(setDocumentLocatorを除く)。

        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。

      • endDocument

        void endDocument​()
          throws SAXException
        非推奨。 
        文書の終了通知を受け取ります。

        SAXパーサーは、このメソッドを構文解析の最後に1回だけ呼び出します。 回復不可能なエラーによって構文解析が途中で破棄されるか、入力が終了するまで、このメソッドは呼び出されません。

        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。

      • startElement

        void startElement​(String name,
                  AttributeList atts)
           throws SAXException
        非推奨。 
        要素の開始通知を受け取ります。

        パーサーはXML文書内の各要素の前でこのメソッドを呼び出します。各startElement()イベントには対応するendElement()イベントがあります。これは、要素が空である場合も変わりません。 対応するendElement()イベントの前に、要素のコンテンツ全部が順番に報告されます。

        要素名に名前空間修飾子が付いていても、この前置修飾子が削除されることはありません。 提供される属性リストには、明示的な値(指定された値またはデフォルト値)を持つ属性のみが含まれます。#IMPLIED属性は含まれません。

        パラメータ:
        name - 要素型名。
        atts - 要素に付加された属性(存在する場合)。
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。
        関連項目:
        endElement(java.lang.String), AttributeList

      • endElement

        void endElement​(String name)
         throws SAXException
        非推奨。 
        要素の終了通知を受け取ります。

        SAXパーサーは、XML文書内の各要素の終わりにこのメソッドを呼び出します。各endElement()イベントには対応するstartElement()イベントがあります。これは、要素が空である場合も変わりません。

        要素名に名前空間前置修飾子が付いていても、この前置修飾子が削除されることはありません。

        パラメータ:
        name - 要素型名
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。

      • characters

        void characters​(char[] ch,
                int start,
                int length)
         throws SAXException
        非推奨。 
        文字データの通知を受け取ります。

        パーサーは、このメソッドを呼び出して、各文字データ・チャンクを報告します。 SAXパーサーは、連続する文字データを単一のチャンクとして、またはいくつかのチャンクに分割して返します。ただし、ロケータから有益な情報を得るためには、単一のイベントに含まれる文字がすべて同じ外部エンティティのものである必要があります。

        アプリケーションは、指定された範囲外の配列を読み取ることはできません。

        一部のパーサーは、このメソッドではなくignorableWhitespace()メソッドを使って、要素コンテンツに含まれる空白文字を報告します。これは、妥当性を検査するパーサーに必須の機能です。

        パラメータ:
        ch - XML文書の文字。
        start - 配列内の開始位置。
        length - 配列から読み取られる文字数。
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。
        関連項目:
        ignorableWhitespace(char[], int, int), Locator

      • ignorableWhitespace

        void ignorableWhitespace​(char[] ch,
                         int start,
                         int length)
                  throws SAXException
        非推奨。 
        要素コンテンツに含まれる無視できる空白文字の通知を受け取ります。

        妥当性を検査するパーサーは、このメソッドを使って、無視できる空白文字のチャンクを報告する必要があります(W3C XML 1.0勧告セクション2.10を参照)。妥当性を検査しないパーサーも、コンテンツ・モデルの構文解析および利用が可能である場合は、このメソッドを使用する場合があります。

        SAXパーサーは、連続するすべての空白文字を単一のチャンクとして、または複数のチャンクに分割して返します。ただし、ロケータから有益な情報を得るためには、単一のイベントに含まれる文字がすべて同じ外部エンティティのものである必要があります。

        アプリケーションは、指定された範囲外の配列を読み取ることはできません。

        パラメータ:
        ch - XML文書の文字。
        start - 配列内の開始位置。
        length - 配列から読み取られる文字数。
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。
        関連項目:
        characters(char[], int, int)

      • processingInstruction

        void processingInstruction​(String target,
                           String data)
                    throws SAXException
        非推奨。 
        処理命令の通知を受け取ります。

        パーサーは、処理命令を検出するたびに1回ずつこのメソッドを呼び出します。処理命令は、メインの文書要素の前後に存在する可能性があります。

        SAXパーサーが、このメソッドを使ってXML宣言を報告することはありません(XML 1.0、セクション2.8)。また、テキスト宣言を報告することもありません(XML 1.0、セクション4.3.1)。

        パラメータ:
        target - 処理命令のターゲット。
        data - 処理命令データ。データが提供されなかった場合はnull。
        例外:
        SAXException - 任意のSAX例外。ほかの例外をラップしている可能性がある。