compact2, compact3

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-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が現在ビジー状態でない場合は、このメソッドを呼び出しても何も実行されません。