public interface LSParser
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 "and" datatype-normalizationがtrue
に設定されている場合、使用される属性の正規化に応じて、XML 1.0属性の正規化によって取得される属性値と異なる場合があります。 パラメータdatatype-normalizationがfalse
に設定されている場合、XML 1.0属性の正規化が行われることが保証され、属性リストに名前空間宣言が含まれていない場合、Element
ノードのattributes
属性は[「XML情報セット」]で定義されたプロパティ[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」も参照してください。
- 導入されたバージョン:
- 1.5
-
フィールドのサマリー
フィールド 修飾子と型 フィールド 説明 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"
"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, LSExceptionLSInput
で識別されたリソースからの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, LSExceptionURI参照「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, LSExceptionLSInput
で識別されたリソースからの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
が現在ビジー状態でない場合は、このメソッドを呼び出しても何も実行されません。
-