|
JavaTM 2 Platform Std. Ed. v1.4.0 |
||||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | ||||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | ||||||||||
文書の論理コンテンツの通知を受け取ります。
このモジュールは、ソースコード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。
ほとんどの SAX アプリケーションが、このインタフェースを実装しています。標準の構文解析イベントの通知を受ける必要がある場合、アプリケーションはこのインタフェースを実装し、setContentHandler メソッドを使ってインスタンスを SAX パーサに登録します。パーサはこのインスタンスを使って、要素や文字データの開始、終了といった標準の文書関連イベントを報告します。
このインタフェース内のイベントの順序は、文書自体に含まれる情報の順序をミラー化したものであり、非常に重要です。たとえば、ある要素の全コンテンツ (文字データ、処理命令、サブ要素など) は、startElement イベントとこれに対応する endElement イベントの間に順番に並べられます。
このインタフェースは、現在では非推奨に指定されている SAX 1.0 の DocumentHandler インタフェースと似ていますが、新たに名前空間のサポートと、妥当性を検証しない XML プロセッサでスキップされたエンティティの報告のサポートが追加されています。
実装者は、java.net パッケージに Java クラス 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 namespaceURI,
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 namespaceURI,
String localName,
String qName,
Attributes atts)
要素の開始通知を受け取ります。 |
void |
startPrefixMapping(String prefix,
String uri)
前置修飾子と URI 名前空間マッピングのスコープを開始します。 |
| メソッドの詳細 |
public void setDocumentLocator(Locator locator)
ロケータが必要な場合は、必須条件ではありませんが、SAX パーサを使用することを強くお勧めします。SAX パーサは、ContentHandler インタフェース内のどのメソッドよりも先にこのメソッドを呼び出し、アプリケーションにロケータを提供します。
アプリケーションは、ロケータを利用して、パーサがエラーを報告しない場合でも文書関連イベントの終了位置を特定することができます。通常、アプリケーションはこの情報を使って固有のエラー (文字コンテンツがアプリケーションの機能規則に沿っていないなど) を報告します。一般に、ロケータから返される情報は不十分であり、検索エンジンでの使用に適していません。
ロケータが正しい情報を返すのは、このインタフェース内でイベント呼び出しが行われている間だけです。それ以外のとき、アプリケーションでロケータの情報を利用するべきではありません。
locator - SAX 文書イベントの位置を返すオブジェクトLocator
public void startDocument()
throws SAXException
SAX パーサは、このメソッドをこのインタフェース内または DTDHandler 内のどのメソッドよりも先に、1 回だけ呼び出します (setDocumentLocator を除く)。
SAXException - SAX 例外。ほかの例外をラップしている可能性があるendDocument()
public void endDocument()
throws SAXException
SAX パーサは、このメソッドを構文解析の最後に 1 回だけ呼び出します。回復不能なエラーによって構文解析が途中で破棄されるか、入力が終了するまで、このメソッドは呼び出されません。
SAXException - SAX 例外。ほかの例外をラップしている可能性があるstartDocument()
public 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)
public 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)
public void startElement(String namespaceURI,
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* 属性) に使用される属性が含まれます。
localName - 前置修飾子を含まないローカル名。名前空間処理が行われない場合は空文字列qName - 前置修飾子を持つ修飾名。修飾名を使用できない場合は空文字列atts - 要素に付加された属性。属性が存在しない場合、空の Attributes オブジェクト
SAXException - SAX 例外。ほかの例外をラップしている可能性があるendElement(java.lang.String, java.lang.String, java.lang.String),
Attributes
public void endElement(String namespaceURI,
String localName,
String qName)
throws SAXException
SAX パーサは、XML 文書内の各要素の終わりにこのメソッドを呼び出します。各 endElement イベントには対応する startElement イベントがあります。これは、要素が空である場合も変わりません。
名前については、startElement を参照してください。
localName - 前置修飾子を含まないローカル名。名前空間処理が行われない場合は空文字列qName - 前置修飾子を持つ XML 1.0 修飾名。修飾名を使用できない場合は空文字列
SAXException - SAX 例外。ほかの例外をラップしている可能性がある
public void characters(char[] ch,
int start,
int length)
throws SAXException
パーサは、このメソッドを呼び出して、各文字データチャンクを報告します。SAX パーサは、連続する文字データを単一のチャンクとして、またはいくつかのチャンクに分割して返します。ただし、ロケータから有益な情報を得るためには、単一のイベントに含まれる文字がすべて同じ外部エンティティのものでなければなりません。
アプリケーションは、指定された範囲外の配列を読み取ることはできません。
一部のパーサは、このメソッドではなく ignorableWhitespace メソッドを使って、要素コンテンツに含まれる空白文字を報告します。これは、妥当性を検証するパーサに必須の機能です。
ch - XML 文書の文字start - 配列内の開始位置length - 配列から読み取られる文字数
SAXException - SAX 例外。ほかの例外をラップしている可能性があるignorableWhitespace(char[], int, int),
Locator
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)
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 例外。ほかの例外をラップしている可能性がある
public 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 2 Platform Std. Ed. v1.4.0 |
||||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | ||||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | ||||||||||
Java、Java 2D、および JDBC は米国ならびにその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.