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

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

HandlerBase, ParserAdapter

推奨されていません。 このインタフェースは、名前空間をサポートする SAX2 の ContentHandler インタフェースで置き換えられています。

public interface DocumentHandler

一般的な文書イベントの通知を受け取ります。

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

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

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

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

導入されたバージョン:

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

public void setDocumentLocator(Locator locator)

推奨されていません。

SAX 文書イベントの発生元を特定するオブジェクトを受け取ります。

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

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

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

パラメータ:

locator - SAX 文書イベントの位置を返すオブジェクト

関連項目:

Locator

startDocument

public void startDocument()
                   throws SAXException

推奨されていません。

文書の開始通知を受け取ります。

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

例外:

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

endDocument

public void endDocument()
                 throws SAXException

推奨されていません。

文書の終了通知を受け取ります。

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

例外:

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

startElement

public void startElement(String name,
                         AttributeList atts)
                  throws SAXException

推奨されていません。

要素の開始通知を受け取ります。

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

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

パラメータ:

name - 要素型名

atts - 要素に付加された属性 (存在する場合)

例外:

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

関連項目:

endElement(java.lang.String), AttributeList

endElement

public void endElement(String name)
                throws SAXException

推奨されていません。

要素の終了通知を受け取ります。

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

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

パラメータ:

name - 要素型名

例外:

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

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

推奨されていません。

文字データの通知を受け取ります。

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

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

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

パラメータ:

ch - XML 文書の文字

start - 配列内の開始位置

length - 配列から読み取られる文字数

例外:

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

関連項目:

ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

public 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

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