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 オブジェクトがサポートしているイベントは次のとおりです。

load

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

progress

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 エラーに関する詳細を取得する場合、 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 エラーに関する詳細を取得する場合、 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 エラーに関する詳細を取得する場合、 DOM アプリケーションは「error-handler」パラメータを使用して DOMErrorHandler を接続する必要がある

abort

void abort()

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