共通 DOM API

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.domConfigerror-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 オブジェクトに自動的に渡されることはありません。この DOMConfiguration オブジェクトの必要なパラメータ値は、DOM アプリケーションによって、Document オブジェクトが参照する DOMConfiguration オブジェクトに渡されます。
[DOM Level 3 Core] で定義されている DOMConfiguration インタフェースで認識されるパラメータに加えて、LSParserDOMConfiguration オブジェクトは次のパラメータを追加または変更します。
"charset-overrides-xml-encoding"
true
[オプション] (デフォルト) HTTP [IETF RFC 2616] などの高次のプロトコルにより、処理される入力ストリームの文字エンコーディングが示されると、XML 宣言またはテキスト宣言 ([XML 1.0] の 4.3.3 項「Character Encoding in Entities」も参照) で指定されたエンコーディングはオーバーライドされます。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 Namespaces] および [XML Namespaces 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 パラメータにより要求された操作が適用されたあとに呼び出されます。たとえば、validatetrue に設定すると、検証はフィルタが呼び出される前に行われます。


setFilter

void setFilter(LSParserFilter filter)
フィルタが提供された場合、実装は DOM ツリー構造を作成しているときにフィルタを呼び出します。フィルタでは、作成中のドキュメントからエレメントを削除したり、解析を早期に終了したりすることを選択できます。
フィルタは、DOMConfiguration パラメータにより要求された操作が適用されたあとに呼び出されます。たとえば、validatetrue に設定すると、検証はフィルタが呼び出される前に行われます。


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 の場合、新規に作成および生成された DocumentLSParser が非同期の場合、このメソッドが返されるときにドキュメントオブジェクトがまだ構築されていない可能性があるので null
例外:
DOMException -
INUSE_ATTRIBUTE_ERR: LSParserLSParser.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 の場合、新規に作成および生成された DocumentLSParser が非同期の場合、このメソッドが返すときにドキュメントオブジェクトはまだ構築されていない可能性があるので 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 の場合、コンテキストノードとして渡されたドキュメントは変更されます。この変更により、ドキュメントの xmlEncodingdocumentURIxmlVersioninputEncodingxmlStandalone、およびほかの同様の属性は、 LSParser.parse() を使って入力ソースを解析するときに設定される値に設定されます。
このメソッドは、LSParser が非同期的な場合 (LSParser.asynctrue) でも常に同期的です。
解析中にエラーが発生した場合は、DOMConfiguration error-handler パラメータに関連する ErrorHandler インスタンスを通じて呼び出し側に通知されます。
parseWithContext を呼び出すとき、validatevalidate-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 も参照)
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 が現在ビジー状態でない場合、このメソッドを呼び出しても何も起こりません。


共通 DOM API

バグや機能要求の報告
Java は、米国およびその他の国における米国 Sun Microsystems, Inc. の商標もしくは登録商標です。
Copyright 2004 Sun Microsystems, Inc. 4150 Network Circle
Santa Clara, California, 95054, U.S.A. All Rights Reserved.