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 オブジェクトにイベントリスナーを登録できるように、非同期 LSParser オブジェクトは events::EventTarget インタフェースも実装すると予測されます。

非同期 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 を保持できない場所で処理命令が検出された場合に返されます。この警告が発生する 1 つの例として、「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 オブジェクトに自動的に渡されることはありません。この DOMConfiguration オブジェクトからの必要なすべてのパラメータ値を Document オブジェクトによって参照される DOMConfiguration オブジェクトに渡す役割は DOM アプリケーションが果たします。
「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--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 が現在ビジー状態でない場合は、このメソッドを呼び出しても何も実行されません。