|
共通 DOM API | |||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
public interface LSParser
さまざまな入力ソースから DOM ツリーを構築または拡張できるオブジェクトへのインタフェースです。
LSParser は、XML を解析し、対応する DOM ドキュメント構造を構築するための API を提供します。LSParser インスタンスは、DOMImplementationLS.createLSParser() メソッドを呼び出して取得できます。
[DOM Level 3 Core] で説明しているように、はじめて LSParser からドキュメントを使用すると、次のようになります。
Attr ノードの value 属性と nodeValue 属性が、XML 1.0 の正規化された属性値を最初に返すことが想定されます。ただし、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 オブジェクトは、次のイベントをサポートします。
LSParser はドキュメントのロードを完了します。LSLoadEvent インタフェースの定義も参照してください。LSParser は、データを解析するときに進捗を通知します。この仕様では、進捗イベントをディスパッチする必要がある正確な時期を定義していません。これは、意識的に実装依存として残されています。アプリケーションが進捗イベントをディスパッチする例を次に示します。パーサがデータの受け取りを開始すると、進捗イベントがディスパッチされ、解析を開始したことが示されます。これ以降、4096 バイトのデータがパーサで受け取られ、処理されるたびに進捗イベントがディスパッチされます。ただし、これはほんの一例であり、実装では、解析中の任意の時に進捗イベントをディスパッチするように設定することも、あるいは、まったくディスパッチしないように設定することもできます。LSProgressEvent インタフェースの定義も参照してください。注: この仕様で定義されたすべてのイベントは、名前空間 URI の「http://www.w3.org/2002/DOMLS」を使用します。
入力ソースを解析中に、エラーはエラーハンドラ (LSParser.domConfig の error-handler パラメータ) を通じてアプリケーションに報告されます。この仕様は、XML やほかのマークアップの解析中に発生する可能性があるすべてのエラーを定義しているわけではありませんが、一部の一般的なエラーのケースを定義しています。この仕様で定義されているエラーと警告の型 (DOMError.type) は次のとおりです。
"check-character-normalization-failure" [error] "doctype-not-allowed" [fatal]true に設定し、doctype が見つかった場合に発生する "no-input-specified" [fatal]LSInput オブジェクトで入力が指定されていない場合に発生する "pi-base-uri-not-preserved" [warning]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]true に設定され、エンティティの置換テキストでアンバインドされた名前空間の接頭辞が見つかった場合に発生する可能性がある実装依存の警告。一部の既存のパーサは、エンティティの置換テキストにあるアンバインドされた名前空間の接頭辞を認識しない可能性があるため、この警告の発生は強制されない"unknown-character-denormalization" [fatal]false に設定し、プロセッサが正規化プロパティを判定できない文字が見つかった場合に発生する "unsupported-encoding" [fatal]"unsupported-media-type" [fatal]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 ツリー構造を作成しているときにフィルタを呼び出します。 |
| フィールドの詳細 |
|---|
static final short ACTION_APPEND_AS_CHILDREN
Element または DocumentFragment でなければなりません。
static final short ACTION_REPLACE_CHILDREN
Element、Document、または DocumentFragment でなければなりません。
static final short ACTION_INSERT_BEFORE
Element または DocumentFragment でなければなりません。
static final short ACTION_INSERT_AFTER
Element または DocumentFragment でなければなりません。
static final short ACTION_REPLACE
Element または DocumentFragment でなければなりません。
| メソッドの詳細 |
|---|
DOMConfiguration getDomConfig()
DOMConfiguration オブジェクト。この DOMConfiguration は解析操作に固有です。この DOMConfiguration オブジェクトのパラメータ値は、解析操作で生成または使用される Document の DOMConfiguration オブジェクトに自動的に渡されることはありません。この DOMConfiguration オブジェクトの必要なパラメータ値は、DOM アプリケーションによって、Document オブジェクトが参照する DOMConfiguration オブジェクトに渡されます。LSParser の DOMConfiguration オブジェクトは次のパラメータを追加または変更します。"charset-overrides-xml-encoding"trueLSInput で明示的にエンコーディングを設定すると、プロトコルのエンコーディングはオーバーライドされます。false"disallow-doctype"truefalse"ignore-unknown-character-denormalizations"truefalse"infoset"DOMConfiguration の定義を参照してください。[DOM Level 3 Core] の場合と異なり、このパラメータは LSParser に対してデフォルトで true に設定されます。"namespaces"truefalse"resource-resolver"LSResourceResolver オブジェクトへの参照、または null。外部リソース (外部 XML エンティティまたは XML スキーマの位置など) が見つかったときにこのパラメータの値が null でない場合、実装ではこのパラメータで参照された LSResourceResolver が外部リソースを解決するように要求します。"supported-media-types-only"truefalse"validate"DOMConfiguration の定義を参照してください。[DOM Level 3 Core] の場合と異なり、このパラメータが false に設定されていても、内部サブセットの処理は常に行われます。"validate-if-schema"DOMConfiguration の定義を参照してください。[DOM Level 3 Core] の場合と異なり、このパラメータが false に設定されていても、内部サブセットの処理は常に行われます。"well-formed"DOMConfiguration の定義を参照してください。[DOM Level 3 Core] の場合と異なり、このパラメータを false に設定することはできません。
LSParserFilter getFilter()
DOMConfiguration パラメータにより要求された操作が適用されたあとに呼び出されます。たとえば、validate を true に設定すると、検証はフィルタが呼び出される前に行われます。
void setFilter(LSParserFilter filter)
DOMConfiguration パラメータにより要求された操作が適用されたあとに呼び出されます。たとえば、validate を true に設定すると、検証はフィルタが呼び出される前に行われます。
boolean getAsync()
LSParser が非同期の場合は true、同期の場合は false。
boolean getBusy()
LSParser が現在ドキュメントのロードでビジー状態の場合は true、そうでない場合は false。
Document parse(LSInput input)
throws DOMException,
LSException
LSInput により識別されたリソースの XML ドキュメントを解析します。
input - ソースドキュメントの読み込み元の LSInput
LSParser が同期 LSParser の場合、新規に作成および生成された Document。LSParser が非同期の場合、このメソッドが返されるときにドキュメントオブジェクトがまだ構築されていない可能性があるので null
DOMException - LSParser の LSParser.busy 属性が true の場合に発生する
LSException - PARSE_ERR: LSParser が XML ドキュメントをロードできなかった場合に発生する。DOM アプリケーションは、エラーの詳細を取得したい場合、error-handler パラメータを使って DOMErrorHandler に接続する必要がある
Document parseURI(String uri)
throws DOMException,
LSException
uri - 読み込まれる XML ドキュメントの位置
LSParser が同期 LSParser の場合、新規に作成および生成された Document。LSParser が非同期の場合、このメソッドが返すときにドキュメントオブジェクトはまだ構築されていない可能性があるので null
DOMException - INVALID_STATE_ERR: LSParser.busy 属性が true の場合に発生する
LSException - PARSE_ERR: LSParser が XML ドキュメントをロードできなかった場合に発生する。DOM アプリケーションは、エラーの詳細を取得したい場合、error-handler パラメータを使って DOMErrorHandler に接続する必要がある
Node parseWithContext(LSInput input,
Node contextArg,
short action)
throws DOMException,
LSException
LSInput により識別されたリソースの XML フラグメントを解析し、context 引数と action 引数を使って指定された位置にある既存のドキュメントに内容を挿入します。入力ストリームを解析するとき、コンテキストノードまたはその親 (結果の挿入場所に応じて異なる) はアンバインドされた名前空間の接頭辞を解決するために使用されます。コンテキストノードの ownerDocument ノードまたはノード自体 (DOCUMENT_NODE 型のノードの場合) はデフォルトの属性と実体参照を解決するために使用されます。 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 構成パラメータの値は無視され、代わりにデフォルト値が常に使用されます。ほかのパラメータは正常に処理され、パーサは 1 つのドキュメント全体が解析された場合と同様に 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 も参照) LSParser がこのメソッドをサポートしていない場合、コンテキストノードが Document 型のコンテキストノードの場合、および DOM 実装が DocumentType の子または Element の子の置換をサポートしていない場合に発生する LSParser.busy 属性が true の場合に発生する
LSException - PARSE_ERR: LSParser が XML フラグメントをロードできなかった場合に発生する。DOM アプリケーションは、エラーの詳細を取得したい場合、error-handler パラメータを使って DOMErrorHandler に接続する必要があるvoid abort()
LSParser により現在ロードされているドキュメントのロードを中止します。LSParser が現在ビジー状態でない場合、このメソッドを呼び出しても何も起こりません。
|
共通 DOM API | |||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||