JavaTM Platform
Standard Ed. 6

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


public interface LSParser

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

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

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

非同期 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
コンテキストノードのすべての子を解析操作の結果に置き換えます。このアクションが機能するには、コンテキストノードが、ElementDocument、あるいは 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 オブジェクトのパラメータ値は、解析操作により作成または使用される DocumentDOMConfiguration オブジェクトに自動的に渡されることはありません。DOM アプリケーションが、 DOMConfiguration オブジェクトから、Document オブジェクトが参照する DOMConfiguration オブジェクトへ必要な パラメータ値を渡す権限を持ちます。
「DOM Level 3 Core」で定義された「DOMConfiguration」 インタフェースで認識されているパラメータに加えて、LSParserDOMConfiguration オブジェクトは次のパラメータを追加または 変更します。
"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:LSParserLSParser.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 である場合、コンテキストノードとして渡される文書は、xmlEncodingdocumentURIxmlVersioninputEncodingxmlStandalone、およびほかのすべての同様の属性が、LSParser.parse() を使用して入力ソースが解析された場合に設定される値に設定されるよう変更されます。
このメソッドは、LSParser が非同期の場合でも (LSParser.asynctrue)、常に同期です。
解析中にエラーが発生すると、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.insertBeforeNode.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 が現在ビジー状態でない場合、このメソッドへの呼び出しは何も影響を与えません。


JavaTM Platform
Standard Ed. 6

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。