org.xml.sax

インタフェース DocumentHandler

既知のすべての実装クラス:

HandlerBase, ParserAdapter

非推奨。

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

public interface DocumentHandler

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

このモジュールは、ソースコード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。詳細については、http://www.saxproject.org を参照してください。

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

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