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, 2014, Oracle and/or its affiliates. All rights reserved.