public interface ContentHandler
このモジュールは、ソースコード、文書ともに公開ドメインに置かれています。したがって、内容に関する保証は一切提供されません。詳細については、http://www.saxproject.org を参照してください。
ほとんどの SAX アプリケーションが、このインタフェースを実装しています。標準の構文解析イベントの通知を受ける必要がある場合、アプリケーションはこのインタフェースを実装し、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 文書イベントの位置を返すオブジェクトLocatorvoid startDocument()
throws SAXException
SAX パーサーは、ほかのイベントがコールバックされる前に 1 回だけこのメソッドを呼び出します (setDocumentLocator 以外)。
SAXException - 任意の SAX 例外。ほかの例外をラップしている可能性があるendDocument()void endDocument()
throws SAXException
このメソッドのマニュアルと ErrorHandler.fatalError(org.xml.sax.SAXParseException) のマニュアルとの間には明らかに矛盾があります。クライアントは、今後のメジャーリリースでこのあいまいさが解決されないかぎり、パーサーが 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 - 接頭辞のマップ先の名前空間 URISAXException - 処理中にクライアントが例外をスローすることがある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, AttributesImplvoid 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 値を使用してサロゲートペアで表されることです。このような文字列は「Astral Planes」と呼ばれ、U+FFFF より大きいコードポイントを持ちます。もう 1 つは、1 つ以上のアクセント文字に結合しているベース文字列などの合成文字列になることです。
char-at-a-time 慣用法を使用するアルゴリズムは文字を分割する場合もあるので、文字単位で処理していると想定してはいけません。これは、XML が属性値、処理命令データ、コメントなどの任意の文字列や、このメソッドから報告されたデータ内にある任意の文字列を許可する場所に関連します。また、一般的には Java コードが国際化されたテキストを操作する場所に関連しますが、発行は XML に一意のものではありません。
一部のパーサーは、このメソッドではなく ignorableWhitespace メソッドを使用して、要素コンテンツに含まれる空白文字を報告します。これは、妥当性を検証するパーサーに必須の機能です。
ch - XML 文書の文字start - 配列内の開始位置length - 配列から読み取られる文字数SAXException - 任意の SAX 例外。ほかの例外をラップしている可能性があるignorableWhitespace(char[], int, int), Locatorvoid 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 例外。ほかの例外をラップしている可能性がある バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.