org.w3c.dom.ls
インタフェース LSParser

public interface LSParser

種々な入力ソースから DOM ツリーを構築または拡張できるオブジェクトへのインタフェースです。

LSParser は、XML を解析し、対応する DOM 文書構造を構築するための API を提供します。LSParser インスタンスは、DOMImplementationLS.createLSParser() メソッドを呼び出して取得できます。

「DOM Level 3 Core」で指定されているように、文書を LSParser を介して利用できる場合

• NODE_TEXT 型の隣接する 2 つのノードは存在しない。また、空のテキストノードも存在しない
• Attr ノードの value 属性と nodeValue 属性は、「XML 1.0 normalized value」を最初に返す。ただし、「validate-if-schema」パラメータと「datatype-normalization」パラメータが true に設定されている場合、使用している属性正規化に応じて、属性値は XML 1.0 属性正規化で取得された属性値とは異なる可能性がある。「datatype-normalization」パラメータが false に設定されている場合は、XML 1.0 属性正規化の発生が保証され、属性リストが名前空間宣言を含まない場合、Element ノードの attributes 属性は「XML Information Set」で定義されている [attributes] プロパティを表す

非同期 LSParser オブジェクトは、events::EventTarget インタフェースも実装します。したがって、非同期 LSParser オブジェクトにイベントリスナーを登録できます。

非同期 LSParser オブジェクトがサポートしているイベントは次のとおりです。

ロード

LSParser は文書のロードを完了 します。LSLoadEvent インタフェースの定義も参照してください。

進捗

LSParser は、データを解析するとき に進捗を通知します。この仕様では、進捗イベントを正確にいつディスパッチ する必要があるか定義しません。つまり、意図的に実装依存のままにしてあり ます。ここでは、アプリケーションが進捗イベントをディスパッチする方法の 一例を示します。パーサがデータの受信を開始すると、進捗イベントがディス パッチされ、解析が開始されたことを示します。これ以降、受信および解析さ れる 4096 バイトのデータごとに進捗イベントがディスパッチされます。 これは一例にすぎませんが、実装では、解析中にいつでも進捗イベントを ディスパッチするように、またはまったくディスパッチしないように選択 できます。LSProgressEvent インタフェースも参照してください。

注: この仕様で定義されているすべてのイベントは、 名前空間 URI 「http://www.w3.org/2002/DOMLS」 を使用します。

入力ソースを解析中、エラーはエラーハンドラ (LSParser.domConfig の 「error-handler」パラメータ) を使用して報告されます。この仕様では、 XML や他のマークアップを解析中に発生する可能性があるすべてのエラーは 定義されていませんが、一般的なエラーケースの一部を定義しています。 この仕様で定義されているエラーの種類 (DOMError.type) と警告は次のとおりです。

"check-character-normalization-failure" [error]

「check-character-normalization」 パラメータが true に設定されていて、文字列で正規化チェックが失敗 した場合に返されます。

"doctype-not-allowed" [fatal]

disallow-doctype 構成パラメータが true に設定されていて、「doctype」が検出された場合に返されます。

"no-input-specified" [fatal]

文書を ロードし、LSInput オブジェクトで入力が指定されない 場合に返されます。

"pi-base-uri-not-preserved" [warning]

処理命令のベース URI を保持できない場所で 処理命令が検出された場合に返されます。この警告が返される一例には、 次のように「entities」 構成パラメータが false に設定されていて、 XML ファイルが解析された場合が挙げられます。

<!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]>
<root> &e; </root>

また、subdir/myentity.ent が次を含む場合

<one> <two/> </one> <?pi 3.14159?>

<more/>

"unbound-prefix-in-entity" [warning]

「namespaces」構成パラメータが true に設定されていて、バインドされていない名前空間の接頭辞が、実体の置換テキストで検出された場合は、実装依存の警告が返されます。この警告を返すのは強制されません。これは、一部の既存のパーサが、実体の置換テキストにあるバインドされていない名前空間の接頭辞を認識しない可能性があるためです。

"unknown-character-denormalization" [fatal]

「ignore-unknown-character-denormalizations」構成パラメータが false に設定されていて、正規化プロパティを判定できない文字が処理で検出された場合に返されます。

"unsupported-encoding" [fatal]

サポートされていないエンコーディングが検出された場合に返されます。

"unsupported-media-type" [fatal]

「supported-media-types-only」構成パラメータが true に設定されていて、サポートされていないメディアタイプが検出された場合に返されます。

定義済みのエラーや警告を返すのに加えて、実装では、IO エラー (「ファイルが見つかりません、アクセス権は拒否されました ...」)、XML 整形式エラーなどを招く他のエラーや警告について実装固有のエラーを返します。

「Document Object Model (DOM) Level 3 Load and Save Specification」も参照してください。

フィールドの概要

static short	ACTION_APPEND_AS_CHILDREN 解析操作の結果をコンテキストノードの子として追加します。
static short	ACTION_INSERT_AFTER 解析操作の結果をコンテキストノードの直後の兄弟ウィジェットとして挿入します。
static short	ACTION_INSERT_BEFORE 解析操作の結果をコンテキストノードの直前の兄弟ウィジェットとして挿入します。
static short	ACTION_REPLACE コンテキストノードを解析操作の結果に置き換えます。
static short	ACTION_REPLACE_CHILDREN コンテキストノードのすべての子を解析操作の結果に置き換えます。

メソッドの概要

void	abort() 現在 LSParser でロードされている文書のローディングを中断します。
boolean	getAsync() LSParser が非同期の場合は true、同期の場合は false です。
boolean	getBusy() LSParser が現在文書をロードしていて、ビジー状態の場合は true、そうでない場合は false です。
DOMConfiguration	getDomConfig() 入力ソースを解析するときに使用される DOMConfiguration オブジェクトです。
LSParserFilter	getFilter() フィルタがある場合、DOM ツリー構造をフィルタが構成しているかのように、実装はフィルタを呼び出します。
Document	parse(LSInput input) LSInput で識別されたリソースから XML 文書を解析します。
Document	parseURI(String uri) URI 参照「IETF RFC 2396」で特定された場所から XML 文書を解析します。
Node	parseWithContext(LSInput input, Node contextArg, short action) LSInput により特定されたリソースから XML フラグメントを解析し、既存の文書の context 引数と action 引数で指定された位置にコンテンツを挿入します。
void	setFilter(LSParserFilter filter) フィルタがある場合、DOM ツリー構造をフィルタが構成しているかのように、実装はフィルタを呼び出します。

フィールドの詳細

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN

解析操作の結果をコンテキストノードの子として追加します。このアクションが機能するには、コンテキストノードが、Element または DocumentFragment になっている必要があります。

関連項目:

定数フィールド値

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN

コンテキストノードのすべての子を解析操作の結果に置き換えます。このアクションが機能するには、コンテキストノードが、Element、Document、あるいは DocumentFragment になっている必要があります。

関連項目:

定数フィールド値

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE

解析操作の結果をコンテキストノードの直前の兄弟ウィジェットとして挿入します。このアクションが機能するには、コンテキストノードの親が、Element または DocumentFragment でになっている必要があります。

関連項目:

定数フィールド値

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER

解析操作の結果をコンテキストノードの直後の兄弟ウィジェットとして挿入します。このアクションが機能するには、コンテキストノードの親が、Element または DocumentFragment になっている必要があります。

関連項目:

定数フィールド値

ACTION_REPLACE

static final short ACTION_REPLACE

コンテキストノードを解析操作の結果に置き換えます。このアクションが機能するには、コンテキストノードが親を持たなければならず、その親が Element または DocumentFragment になっている必要があります。

関連項目:

定数フィールド値

メソッドの詳細

getDomConfig

DOMConfiguration getDomConfig()

入力ソースを解析するときに使用される DOMConfiguration オブジェクトです。この DOMConfiguration は、解析操作に固有です。 また、DOMConfiguration オブジェクトのパラメータ値は、解析操作に より作成または使用される Document の DOMConfiguration オブジェクトに自動的に渡されることはありません。DOM アプリケーションが、 DOMConfiguration オブジェクトから、Document オブジェクトが参照する DOMConfiguration オブジェクトへ必要な パラメータ値を渡す権限を持ちます。
「DOM Level 3 Core」で定義された「DOMConfiguration」 インタフェースで認識されているパラメータに加えて、LSParser の DOMConfiguration オブジェクトは次のパラメータを追加または 変更します。

"charset-overrides-xml-encoding"

true

「オプション」(デフォルト) HTTP「IETF RFC 2616」 などの高位レベルプロトコルが処理中の入力ストリームの文字エンコーディングを 指示する場合、XML 宣言やテキスト宣言 ( 「XML 1.0」のセクション 4.3.3 「実体の文字エンコーディング」も参照) で指定されたエンコーディングは、高位レベルプロトコルによる文字 エンコーディングによりオーバーライドされます。また、LSInput で明示的にエンコーディングを設定すると、プロトコルのエンコーディングは オーバーライドされます。

false

「必須」 パーサは、高位レベルプロトコルの文字セットエンコーディング情報を無視します。

"disallow-doctype"

true

「オプション」文書を解析中に doctype ノードが 見つかった場合、致命的なエラーの「doctype-not-allowed」をスローします。 これは、doctype ノードが許可されない SOAP エンベロープのようなものを扱うと きに役に立ちます。

false

「必須」 (デフォルト) 文書で doctype ノードを許可します。

"ignore-unknown-character-denormalizations"

true

「必須」(デフォルト) 「XML 1.1」をサポートしていて、完全な正規化を確認中に、正規化プロパティ を判定できない文字をプロセッサが検出した場合、プロセッサはその文字で生じ る可能性がある不完全な正規化を無視します。このパラメータは 「XML 1.0」 については無視されます。

false

「オプション」正規化プロパティを判定できない文字をプロセッサが 検出した場合、致命的なエラーの「unknown-character-denormalization」 を通知します。

"infoset"

このパラメータの詳細については、DOMConfiguration の定義を参照してください。「DOM Level 3 Core」 とは異なり、このパラメータは LSParser に対してデフォルトで true に設定されます。

"namespaces"

true

「必須」(デフォルト) XML 名前空間 と XML 名前空間 1.1 の定義に従って名前空間処理を行います。

false

「オプション」名前空間処理を実行しません。

"resource-resolver"

「必須」 LSResourceResolver オブジェクトに対する参照、または null。 外部リソース (外部 XML 実体または XML スキーマロケーション) が検出され たときに、このパラメータが null ではない場合、実装はこのパラメータで 参照された LSResourceResolver によりリソースを解決するように 要求します。

"supported-media-types-only"

true

「オプション」解析された リソースのメディアタイプがサポートされているメディアタイプであることを チェックします。サポートされていないメディアタイプが検出された場合、 型「unsupported-media-type」の致命的エラーが返されます。 「IETF RFC 3023」 で定義されているメディアタイプは常に受け入れられます。

false

「必須」(デフォルト) 任意のメディアタイプを 受け入れます。

"validate"

このパラメータの詳細については、DOMConfiguration の定義を 参照してください。「DOM Level 3 Core」 とは異なり、このパラメータが false に設定された場合、 内部サブセットの処理は常に実行されます。

"validate-if-schema"

このパラメータの詳細については、 DOMConfiguration の定義を参照してください。 「DOM Level 3 Core」とは異なり、このパラメータが false に設定された場合、内部サブセットの処理は常に実行されます。

"well-formed"

このパラメータの詳細については、 DOMConfiguration の定義を参照してください。 「DOM Level 3 Core」とは異なり、このパラメータは false に設定できません。

getFilter

LSParserFilter getFilter()

フィルタがある場合、DOM ツリー構造をフィルタが構成しているかのように、実装はフィルタを呼び出します。フィルタでは、構築している文書から要素を削除したり、初期に解析を終了したりすることを選択できます。
フィルタは、DOMConfiguration パラメータで要求された操作が適用されたあとに呼び出されます。たとえば、「validate」が true に設定されていると、検証はフィルタが呼び出される前に実行されます。

setFilter

void setFilter(LSParserFilter filter)

フィルタがある場合、DOM ツリー構造をフィルタが構成しているかのように、実装はフィルタを呼び出します。フィルタでは、構築している文書から要素を削除したり、初期に解析を終了したりすることを選択できます。
フィルタは、DOMConfiguration パラメータで要求された操作が適用されたあとに呼び出されます。たとえば、「validate」が true に設定されていると、検証はフィルタが呼び出される前に実行されます。

getAsync

boolean getAsync()

LSParser が非同期の場合は true、同期の場合は false です。

getBusy

boolean getBusy()

LSParser が現在文書をロードしていて、ビジー状態の場合は true、そうでない場合は false です。

parse

Document parse(LSInput input)
               throws DOMException,
                      LSException

LSInput で識別されたリソースから XML 文書を解析します。

パラメータ:

input - 文書のソースが読み取られる LSInput

戻り値:

LSParser が同期 LSParser の場合は、新しく作成され、値が設定された Document が返される。LSParser が非同期の場合は、このメソッドが値を返すときに文書オブジェクトがまだ構築されていない可能性があるので、null が返される

例外:

DOMException - INVALID_STATE_ERR: LSParser の LSParser.busy 属性が true の場合

LSException - PARSE_ERR: LSParser が XML 文書をロードできなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

parseURI

Document parseURI(String uri)
                  throws DOMException,
                         LSException

URI 参照「IETF RFC 2396」で特定された場所から XML 文書を解析します。URI にフラグメント識別子が含まれる場合 (「IETF RFC 2396」のセクション 4.1 を参照)、この仕様では動作は定義されていません。動作は、この仕様の将来バージョンで定義される可能性があります。

パラメータ:

uri - 読み取られる XML 文書の場所

戻り値:

LSParser が同期 LSParser の場合は、新しく作成され、値が設定された Document が返される。エラーが発生した場合は null が返される。LSParser が非同期の場合は、このメソッドが値を返すときに文書オブジェクトがまだ構築されていない可能性があるので、null が返される

例外:

DOMException - INVALID_STATE_ERR: LSParser.busy 属性が true の場合

LSException - PARSE_ERR: LSParser が XML 文書をロードできなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

parseWithContext

Node parseWithContext(LSInput input,
                      Node contextArg,
                      short action)
                      throws DOMException,
                             LSException

LSInput により特定されたリソースから XML フラグメントを解析し、既存の文書の context 引数と action 引数で指定された位置にコンテンツを挿入します。入力ストリームを解析中、コンテキストノード (またはその親。結果が挿入される場所に応じて異なる) はバインドされていない名前空間接頭辞を解決するために使用されます。コンテキストノードの ownerDocument ノード (ノード型が DOCUMENT_NODE の場合はノード自体) は、デフォルト属性と実体参照を解決するために使用されます。
新しいデータが文書に挿入されるとき、コンテキストノードの新しい直接の子または兄弟ウィジェットごとに少なくとも 1 つの変更イベントがトリガされます。
コンテキストノードが Document ノードであり、アクションが ACTION_REPLACE_CHILDREN である場合、コンテキストノードとして渡される文書は、xmlEncoding、documentURI、xmlVersion、inputEncoding、xmlStandalone、および他のすべての同様の属性が、LSParser.parse() を使用して入力ソースが解析された場合に設定される値に設定されるよう変更されます。
このメソッドは、LSParser が非同期の場合でも (LSParser.async は true)、常に同期です。
解析中にエラーが発生すると、DOMConfiguration の「error-handler」パラメータに関連する ErrorHandler インスタンスを通じて呼び出し側に通知されます。
parseWithContext を呼び出しているときは、「validate」、「validate-if-schema」、「element-content-whitespace」の構成パラメータの値は無視され、常にデフォルト値が使用されます。他のパラメータは通常どおり使用され、パーサは、文書全体を解析したかのように、LSParserFilter を呼び出します。

パラメータ:

input - ソース文書が読み取られる LSInput。ソース文書は、XML フラグメント、つまり完全な XML 文書 (コンテキストノードが DOCUMENT_NODE 型、アクションが ACTION_REPLACE_CHILDREN である場合を除く)、DOCTYPE (内部サブセット)、実体宣言、表記法宣言、あるいは XML 宣言またはテキスト宣言) 以外になる必要がある

contextArg - 解析されるデータのコンテキストとして使用されるノード。このノードは Document ノード、DocumentFragment ノード、あるいは Element ノードの子として許可される型のノードになる必要がある。たとえば、Attribute ノードは不可

action - このパラメータは、挿入されている新しいノードセットとコンテキストノードの既存の子との間で実行する必要があるアクションを表す。考えられるアクションのセットは前述の ACTION_TYPES で定義される

戻り値:

解析操作の結果であるノード。結果がトップレベルノードよりも高位にある場合は、最初のノードが返される

例外:

DOMException - HIERARCHY_REQUEST_ERR: コンテンツをコンテキストノードの子に置き換えたり、コンテキストノードの子の前や後ろに挿入できない場合 (「DOM Level 3 Core」の Node.insertBefore や Node.replaceChild も参照)
NOT_SUPPORTED_ERR: LSParser がこのメソッドをサポートしない場合、またはコンテキストノードが型 Document のノードで、DOM 実装が子 DocumentType や子 Element の置き換えをサポートしない場合
NO_MODIFICATION_ALLOWED_ERR: コンテキストノードが読み取り専用ノードで、コンテキストがその子のリストに追加されている場合、またはコンテキストノードの親ノードが読み取り専用ノードで、コンテキストがその子のリストに挿入されている場合
INVALID_STATE_ERR: LSParser.busy 属性が true の場合

LSException - PARSE_ERR: LSParser が XML フラグメントをロードできなかった場合。DOM エラーに関する詳細を取得する場合、アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

abort

void abort()

現在 LSParser でロードされている文書のローディングを中断します。LSParser が現在ビジー状態でない場合、このメソッドへの呼び出しは何も影響を与えません。