|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
public interface ContentHandler
文書の論理コンテンツの通知を受け取ります。
このモジュールは、ソースコード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。詳細については、http://www.saxproject.org を参照してください。
ほとんどの SAX アプリケーションが、このインタフェースを実装しています。標準の構文解析イベントの通知を受ける必要がある場合、アプリケーションはこのインタフェースを実装し、 org.xml.sax.XMLReader#setContentHandler setContentHandler メソッドを使用してインスタンスを SAX パーサーに登録します。パーサーはこのインスタンスを使用して、要素や文字データの開始、終了といった標準の文書関連イベントを報告します。
このインタフェース内のイベントの順序は、文書自体に含まれる情報の順序をミラー化したものであり、非常に重要です。たとえば、ある要素の全コンテンツ (文字データ、処理命令、サブ要素など) は、startElement イベントとこれに対応する endElement イベントの間に順番に並べられます。
このインタフェースは、現在では非推奨に指定されている SAX 1.0 の DocumentHandler インタフェースと似ていますが、新たに名前空間のサポートと、妥当性を検証しない XML プロセッサでスキップされたエンティティーの報告のサポートが追加されています。
実装者は、java.net パッケージに ContentHandler クラスが含まれている点を考慮して、次のような処理は必ず避けてください。
import java.net.*; import org.xml.sax.*;
通常、「import ...*」を使用したプログラムは、ずさんな (sloppy) プログラムと見なされます。 ユーザーは、バグよりもこの点に注意を払う必要があります。
XMLReader,
DTDHandler,
ErrorHandler| メソッドの概要 | |
|---|---|
void |
characters(char[] ch,
int start,
int length)
文字データの通知を受け取ります。 |
void |
endDocument()
文書の終了通知を受け取ります。 |
void |
endElement(String uri,
String localName,
String qName)
要素の終了通知を受け取ります。 |
void |
endPrefixMapping(String prefix)
前置修飾子と URI のマッピングのスコープを終了します。 |
void |
ignorableWhitespace(char[] ch,
int start,
int length)
要素コンテンツに含まれる無視できる空白文字の通知を受け取ります。 |
void |
processingInstruction(String target,
String data)
処理命令の通知を受け取ります。 |
void |
setDocumentLocator(Locator locator)
SAX 文書イベントの発生元を特定するオブジェクトを受け取ります。 |
void |
skippedEntity(String name)
スキップされたエンティティーの通知を受け取ります。 |
void |
startDocument()
文書の開始通知を受け取ります。 |
void |
startElement(String uri,
String localName,
String qName,
Attributes atts)
要素の開始通知を受け取ります。 |
void |
startPrefixMapping(String prefix,
String uri)
前置修飾子と URI 名前空間マッピングのスコープを開始します。 |
| メソッドの詳細 |
|---|
void setDocumentLocator(Locator locator)
ロケータが必要な場合は、必須条件ではありませんが、SAX パーサーを使用することを強くお勧めします。SAX パーサーは、ContentHandler インタフェース内のどのメソッドよりも先にこのメソッドを呼び出し、アプリケーションにロケータを提供します。
アプリケーションは、ロケータを利用して、パーサーがエラーを報告しない場合でも文書関連イベントの終了位置を特定することができます。通常、アプリケーションはこの情報を使って固有のエラー (文字コンテンツがアプリケーションの機能規則に沿っていないなど) を報告します。一般に、ロケータから返される情報は不十分であり、検索エンジンでの使用に適していません。
ロケータは、startDocument が返されたあと、endDocument が呼び出される前の呼び出し SAX イベントコールバック中にかぎり適正な情報を返します。それ以外のとき、アプリケーションでロケータの情報を利用するべきではありません。
locator - SAX 文書イベントの位置を
返すオブジェクトLocator
void startDocument()
throws SAXException
SAX パーサーは、ほかのイベントがコールバックされる前に 1 回だけこのメソッドを呼び出します (setDocumentLocator 以外)。
SAXException - SAX 例外。
ほかの例外をラップしている可能性があるendDocument()
void endDocument()
throws SAXException
このメソッドのマニュアルと endDocument() のマニュアルとの間には明らかに矛盾があります。クライアントは、今後のメジャーリリースでこのあいまいさが解決されないかぎり、パーサーが fatalError() を報告したり例外をスローしたときに endDocument() が呼び出されるかどうかを仮定しないようにする必要があります。
SAX パーサーは、このメソッドを構文解析の最後に 1 回だけ呼び出します。回復不可能なエラーによって構文解析が途中で破棄されるか、入力が終了するまで、このメソッドは呼び出されません。
SAXException - SAX 例外。
ほかの例外をラップしている可能性があるstartDocument()
void startPrefixMapping(String prefix,
String uri)
throws SAXException
通常の名前空間処理はイベントから提供される情報を必要としません。SAX の XML リーダーは、http://xml.org/sax/features/namespaces 機能の値が true (デフォルト) に設定されていると、要素および属性名の接頭辞を自動的に置き換えます。
しかし、アプリケーションによって文字データや属性値の中で使用される場合、接頭辞を安全に展開できません。 こうしたアプリケーションには、必要に応じて、start/endPrefixMapping イベントにより、接頭辞をアプリケーションコンテキスト内で拡張するために必要な情報が提供されます。
start/endPrefixMapping イベントがそれぞれ正しく入れ子にされるかどうかは保証されません。すべての startPrefixMapping イベントは、対応する startElement イベントの前にただちに発生し、すべての endPrefixMapping イベントは対応する endElement イベントのあとで発生しますが、これらの順番は保証されていません。
「xml」接頭辞は事前に宣言される不変の修飾子なので、その start/endPrefixMapping イベントは存在しません。
prefix - 宣言される名前空間接頭辞。
デフォルトによる要素の名前空間に使用する空文字列
(接頭辞なし)uri - 接頭辞のマップ先名前空間 URI
SAXException - 処理中にクライアントが
例外をスローすることがあるendPrefixMapping(java.lang.String),
startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)
void endPrefixMapping(String prefix)
throws SAXException
詳細は startPrefixMapping を参照してください。これらのイベントは常に、対応する endElement イベントのあとにすぐ発生しますが、endPrefixMapping イベントの順番は保証されていません。
prefix - マッピングされた接頭辞。
デフォルトマッピングのスコープが終了する場合は空文字列になる
SAXException - 処理中にクライアントが
例外をスローすることがあるstartPrefixMapping(java.lang.String, java.lang.String),
endElement(java.lang.String, java.lang.String, java.lang.String)
void startElement(String uri,
String localName,
String qName,
Attributes atts)
throws SAXException
パーサーは XML 文書内の各要素の前でこのメソッドを呼び出します。 各 startElement イベントには対応する endElement イベントがあります。これは、要素が空である場合も変わりません。 対応する endElement イベントの前に、要素のコンテンツ全部が順番に報告されます。
このイベントでは、各要素に最大 3 つの名前コンポーネントを許可します。
http://xml.org/sax/features/namespaces プロパティーおよび http://xml.org/sax/features/namespace-prefixes プロパティーの値により、これらのいずれか、または全部が提供されます。
提供される属性リストには、明示的な値 (指定された値またはデフォルト値) を持つ属性だけが含まれます。#IMPLIED 属性は含まれません。このリストには、http://xml.org/sax/features/namespace-prefixes プロパティーが true (デフォルトの設定は false。 true のサポートはオプション) である場合に限り、名前空間定義 (xmlns* 属性) に使用される属性が含まれます。
属性値は、characters() のように 2 つ以上の char 値を必要とする文字列を持つ場合があります。
uri - 名前空間 URI。
要素が名前空間 URI を持たない場合、
または名前空間処理が行われない場合は空文字列localName - 接頭辞を持たないローカル名。
名前空間処理が行われない場合は
空文字列qName - 接頭辞を持つ修飾名。
修飾名を使用できない場合は空文字列atts - 要素に追加された属性。属性が
存在しない場合、
空の Attributes オブジェクト。startElement が返されたあとの
このオブジェクトの値は定義されない
SAXException - SAX 例外。
ほかの例外をラップしている可能性があるendElement(java.lang.String, java.lang.String, java.lang.String),
Attributes,
AttributesImpl
void endElement(String uri,
String localName,
String qName)
throws SAXException
SAX パーサーは、XML 文書内の各要素の終わりにこのメソッドを呼び出します。 各 endElement イベントには対応する startElement イベントがあります。 これは、要素が空である場合も変わりません。
名前については、startElement を参照してください。
uri - 名前空間 URI。
要素が名前空間 URI を持たない場合、
または名前空間処理が行われない場合は空文字列localName - 接頭辞を持たないローカル名。
名前空間処理が行われない場合は
空文字列qName - 接頭辞を持つ XML 修飾名。
修飾名を使用できない場合は空文字列
SAXException - SAX 例外。
ほかの例外をラップしている可能性がある
void characters(char[] ch,
int start,
int length)
throws SAXException
パーサーは、このメソッドを呼び出して、各文字データチャンクを報告します。SAX パーサーは、連続する文字データを単一のチャンクとして、またはいくつかのチャンクに分割して返します。 ただし、ロケータから有益な情報を得るためには、単一のイベントに含まれる文字がすべて同じ外部エンティティーのものでなければいけません。
アプリケーションは、指定された範囲外の配列を読み取ることはできません。
それぞれの文字列は 2 つ以上の Java char 値で構成されます。文字列を 16 ビット以内で表示することはできないため、2 つの重要なケースが発生します。1 つは、文字列が 2 つの Unicode 値を使用して「Surrogate Pair」で表されることです。このような文字列は「Astral Planes」と呼ばれ、U+FFFF より大きいコードポイントを持ちます。もう 1 つは、1 つ以上のアクセント文字に結合しているベース文字列などの合成文字列になることです。
char-at-a-time 慣用法を使用するアルゴリズムは文字列を分割する場合もあるので、文字列単位で処理していると想定してはいけません。これは、XML が属性値、処理命令データ、コメントなどの任意の文字列や、このメソッドから報告されたデータ内にある任意の文字列を許可する場所に関連します。また、一般的には Java コードが国際化されたテキストを操作する場所に関連しますが、発行は XML に一意のものではありません。
一部のパーサーは、このメソッドではなく ignorableWhitespace メソッドを使用して、要素コンテンツに含まれる空白文字を報告します。 これは、妥当性を検証するパーサーに「必須」の機能です。
ch - XML 文書の文字start - 配列内の開始位置length - 配列から読み取られる文字数
SAXException - SAX 例外。
ほかの例外をラップしている可能性があるignorableWhitespace(char[], int, int),
Locator
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)
void processingInstruction(String target,
String data)
throws SAXException
パーサーは、処理命令を検出するたびに 1 回ずつこのメソッドを呼び出します。処理命令は、メインの文書要素の前後に存在する可能性があります。
SAX パーサーが、このメソッドを使用して XML 宣言を報告することはありません (XML 1.0、セクション 2.8)。 また、テキスト宣言を報告することもありません (XML 1.0、セクション 4.3.1)。
処理命令データは、characters() のように 2 つ以上の char 値を必要とする文字列を持つ場合があります。
target - 処理命令のターゲットdata - 処理命令を受けるデータ。
データが提供されない場合は null。データには、
ターゲットと自身を区別するための空白文字は含まれない
SAXException - SAX 例外。
ほかの例外をラップしている可能性がある
void skippedEntity(String name)
throws SAXException
パーサーは、エンティティーがスキップされるたびに 1 回ずつこのメソッドを呼び出します。妥当性を検証しないプロセッサは、(エンティティーが外部 DTD サブセット内に定義されているなどの理由で) 宣言が検出されないとエンティティーをスキップします。すべてのプロセッサは、http://xml.org/sax/features/external-general-entities プロパティーと http://xml.org/sax/features/external-parameter-entities プロパティーの値により、外部エンティティーをスキップする可能性があります。
name - スキップされたエンティティーの名前。パラメータエンティティーの場合、
この名前は「%」で始まる。
外部 DTD サブセットの場合、
文字列「[dtd]」で始まる
SAXException - SAX 例外。
ほかの例外をラップしている可能性がある
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。