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

インタフェースDocumentHandler

既知のすべての実装クラス:
HandlerBase, ParserAdapter
@Deprecated(since="1.5") public interface DocumentHandler
非推奨。
このインタフェースは、名前空間サポートを含むSAX2 ContentHandlerインタフェースで置き換えられています。
一般的な文書イベントの通知を受け取ります。

これは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

  • メソッドのサマリー

    修飾子と型
    メソッド
    説明
    void
    characters​(char[] ch, int start, int length)
    非推奨。
    文字データの通知を受け取ります。
    void
    endDocument()
    非推奨。
    文書の終了通知を受け取ります。
    void
    endElement​(String name)
    非推奨。
    要素の終了通知を受け取ります。
    void
    ignorableWhitespace​(char[] ch, int start, int length)
    非推奨。
    要素コンテンツに含まれる無視できる空白文字の通知を受け取ります。
    void
    processingInstruction​(String target, String data)
    非推奨。
    処理命令の通知を受け取ります。
    void
    setDocumentLocator​(Locator locator)
    非推奨。
    SAX文書イベントの発生元を特定するオブジェクトを受け取ります。
    void
    startDocument()
    非推奨。
    文書の開始通知を受け取ります。
    void
    startElement​(String name, AttributeList atts)
    非推奨。
    要素の開始通知を受け取ります。

  • メソッドの詳細

    • 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例外。ほかの例外をラップしている可能性があります。