共通 DOM API

org.w3c.dom
インタフェース DOMConfiguration


public interface DOMConfiguration

DOMConfiguration インタフェースは、ドキュメントの構成を表し、認識されたパラメータの表を保持します。この構成を使用すると、CDATASection ノードを Text ノードに置換したり、Document の検証を要求されたときに使用する必要があるスキーマの型を指定したりするなど、Document.normalizeDocument() の動作を変更できます。また、DOMConfiguration オブジェクトは DOMParser インタフェースと DOMSerializer インタフェースの [DOM Level 3 Load および Save] でも使用されます。

DOMConfiguration オブジェクトで使用されるパラメータ名は、DOM Level 3 仕様全体を通して定義されています。パラメータ名では大文字と小文字を区別します。競合する可能性を回避するために、規則として、DOM 仕様以外で定義されたパラメータを参照する名前は一意にする必要があります。パラメータはプロパティとして公開されるので、名前は「-」(HYPHEN-MINUS) 文字を追加して、「Identifiers of [Unicode]」のセクション 5.16 項に従うことをお勧めしますが、DOM 実装により強制はされません。DOM Level 3 Core 実装は、この仕様で定義されたすべてのパラメータを認識する必要があります。また、一部のパラメータ値は、実装でサポートすることが必要な場合もあります。パラメータの定義を参照して、値がサポートされている必要があるかどうかを確認してください。

注: パラメータは SAX2 [SAX] で使用される機能とプロパティに似ています。

DOM で定義されているパラメータを次に示します。

"canonical-form"
true
[オプション] [Canonical XML] で指定された規則に従って、ツリーから DocumentType ノード (存在する場合) を削除したり、各要素から余分な名前空間宣言を削除したりするなど、ドキュメントの正規化を行います。この正規化は、DOM で表すことができるものに制限されます。特に、DOM での属性の順序を指定する方法はありません。また、このパラメータを true に設定すると、次に示すパラメータの状態も設定されます。あとでこれらのパラメータの 1 つの状態を変更すると、canonical-form は false に戻ります。false に設定されるパラメータには、entities、normalize-characters、cdata-sections があります。true に設定されるパラメータには、namespaces、namespace-declarations、well-formed、element-content-whitespace があります。ほかのパラメータは、パラメータの記述で明示的に指定されないかぎり、変更されません。
false
[必須] (デフォルト) ドキュメントを正規化しません。
"cdata-sections"
true
[必須] (デフォルト) ドキュメントの CDATASection ノードを保持します。
false
[必須] ドキュメントの CDATASection ノードを Text ノードに変換します。新規 Text ノードは、隣接する Text ノードと結合されます。.
"check-character-normalization"
true
[オプション] ドキュメントの文字が [XML 1.1] の付録 B の規定に従って完全に正規化されたことをチェックします。正規化のチェックに失敗する文字のシーケンスが見つかった場合、check-character-normalization-failure と同等の DOMError.type によるエラーが発行されます。
false
[必須] (デフォルト) 文字が正規化されているかどうかをチェックしません。
"comments"
true
[必須] (デフォルト) ドキュメントの Comment ノードを保持します。
false
[必須] ドキュメントの Comment ノードを破棄します。
"datatype-normalization"
true
[オプション] XML スキーマの場合は、XML スキーマ正規化値 などツリーのスキーマ正規化値を公開します。このパラメータはスキーマ情報を必要とするので、validate パラメータも true に設定されます。validate パラメータが false のときにこのパラメータを起動しても、効果はありません。また、スキーマ正規化は行われません。

注: ドキュメントには XML 1.0 処理の結果が含まれるので、[XML 1.0] の 3.3.3 項で規定されているように、このパラメータは属性値には適用されません。また、Document Type Definition (DTD) 以外のスキーマ言語だけに有効です。

false
[必須] (デフォルト) ツリーでスキーマ正規化を行いません。
"element-content-whitespace"
true
[必須] (デフォルト) ドキュメントのすべての空白を保持します。
false
[オプション] 要素内容の空白 で説明されているように、要素の内容に空白を含むすべての Text ノードを破棄します。実装は、Text.isElementContentWhitespace を使って Text ノードを破棄する必要があるかどうかを判定することが想定されています。
"entities"
true
[必須] (デフォルト) ドキュメントの EntityReference ノードを保持します。
false
[必須] ノードを削除し、削除された位置にエンティティ展開を直接配置します。Text ノードは Node.normalize で定義されているように正規化されます。展開されていない実体参照だけがドキュメントに保持されます。

注: このパラメータは Entity ノードに影響を及ぼしません。

"error-handler"
[必須] DOMErrorHandler オブジェクトを含めます。ドキュメントでエラーが見つかった場合、実装はこのパラメータを使って登録された DOMErrorHandler を呼び出します。実装はデフォルトの DOMErrorHandler オブジェクトを提供できます。このオブジェクトが呼び出されると、DOMError.relatedData にはエラーが見つかった場所にもっとも近いノードが含まれます。実装がエラーの発生したノードを判定できない場合、DOMError.relatedData には Document ノードが含まれます。エラーハンドラ内からのドキュメントへの変異は実装に依存する動作を生じます。
"infoset"
true
[必須] XML 情報セット [XML Information Set] で定義されている情報をドキュメントに保持します。これにより、validate-if-schema、entities、datatype-normalization、cdata-sections パラメータは強制的に false に設定されます。また、namespace-declarations、well-formed、element-content-whitespace、comments、namespaces パラメータは強制的に true に設定されます。ほかのパラメータは、パラメータの記述で明示的に指定されないかぎり、変更されません。getParameter を使ってこのパラメータを照会すると、上述の個々のパラメータが適切に設定されている場合にかぎり、true が返されます。
false
infosetfalse に設定しても何も効果はありません。
"namespaces"
true
[必須] (デフォルト) 定義された名前空間処理を行います。
false
[オプション] 名前空間処理を行いません。
"namespace-declarations"
このパラメータは、namespaces パラメータを false に設定している場合、効果はありません。
true
[必須] (デフォルト) スキーマで指定またはデフォルト設定された名前空間宣言属性をドキュメントに含めます。[XML Namespaces] と [XML Namespaces 1.1] の「Declaring Namespaces」の項も参照してください。
false
[必須] すべての名前空間宣言属性を破棄します。このパラメータを false に設定しても、名前空間接頭辞は保持されます。
"normalize-characters"
true
[オプション] [XML 1.1] の付録 B で定義されているようにドキュメントの文字を 完全に正規化 します。
false
[必須] (デフォルト) 文字の正規化を行いません。
"schema-location"
[オプション] 空白で区切られた URI のリストを含む DOMString オブジェクトを表します。このリストは検証を行う必要があるスキーマ、つまり現在のスキーマを表します。このリストで参照されるスキーマの型は、schema-type を使って指定された型に一致する必要があります。一致しない場合、実装の動作は未定義です。このプロパティを使って指定されたスキーマは、ドキュメント自体で指定されたスキーマ情報よりも優先されます。名前空間対応スキーマの場合、このプロパティを使って指定されたスキーマと、ドキュメントインスタンスで指定されたスキーマ (schemaLocation 属性を使用)、スキーマドキュメントで指定されたスキーマ (スキーマ import 機構を使用) が同じ targetNamespace を共有する場合は、ユーザがこのプロパティを使って指定したスキーマが使用されます。このプロパティを使用して指定された 2 つのスキーマが同じ targetNamespace を共有するか、名前空間を持たない場合、動作は実装に依存します。場所が指定されなかった場合、このパラメータは null です。

注: "schema-location" パラメータは、schema-type パラメータが設定された場合を除き、無視されます。Document.documentURI を設定することを強く推奨します。これにより、実装は参照された外部エンティティを正常に解決できます。

"schema-type"
[オプション] 絶対 URI を含んでいて、ドキュメントの検証に使用されるスキーマ言語の種類を示す DOMString オブジェクトを表します。絶対 URI では字句チェックは行われません。このパラメータを設定しない場合は、サポートされているスキーマ言語やロード時に使用されるスキーマ言語に基づいて、実装でデフォルト値を指定できます。値が指定されない場合、このパラメータは null です。

注: XML スキーマ [XML Schema Part 1] の場合、アプリケーションで値 "http://www.w3.org/2001/XMLSchema" を使用する必要があります。XML DTD [XML 1.0] の場合、アプリケーションで値 "http://www.w3.org/TR/REC-xml" を使用する必要がある。ほかのスキーマ言語は、W3C の範囲に含まれないため、このメソッドを使用するには絶対 URI を推奨します。

"split-cdata-sections"
true
[必須] (デフォルト) CDATA セクションの終了マーカ 「]]>」を含む複数の CDATA セクションを分割します。CDATA セクションが分割されると、DOMError.type"cdata-sections-splitted" であり、および分割の結果生じた複数の CDATASection ノードの最初のものに等しい DOMError.relatedData が発行されます。
false
[必須] 表示不可能な文字が CDATASection に含まれる場合にエラーを通知します。
"validate"
true
[オプション] ドキュメントが [XML 1.0] の定義に従って正規化されるとき、XML スキーマ、DTD、およびほかの種類のスキーマ表現など、ドキュメントのスキーマに対する検証を要求します。検証エラーが見つかった場合やスキーマが見つからなかった場合は、エラーハンドラに通知されます。スキーマ正規化値は、datatype-normalization パラメータが true に設定されていないかぎり、使用されているスキーマに従って公開されません。このパラメータは、次のものを再評価します。
  • Attr インタフェースの説明で示されているように、Attr.specifiedfalse である属性ノード
  • すべての Text ノードの Text.isElementContentWhitespace 属性の値
  • すべての Attr ノードの Attr.isId 属性の値
  • Element.schemaTypeInfo 属性と Attr.schemaTypeInfo 属性

注: validate-if-schema と validate は相互に排他的です。一方を true に設定すると、他方は false に設定されます。アプリケーションでは、ドキュメントの検証時に well-formed パラメータをこのオプションのデフォルトの true に設定することも考慮する必要があります。

false
[必須] (デフォルト) 内部サブセット処理を含め、スキーマ処理を行いません。デフォルトの属性値情報は維持されます。validate-if-schema が true の場合は、引き続き検証が発生する可能性があります。
"validate-if-schema"
true
[オプション] ドキュメント要素の宣言が、スキーマ (XML スキーマ、DTD、またはほかの種類のスキーマなど、確認された位置に無関係) で確認できる場合のみ検証を有効にします。検証が有効になると、このパラメータの動作は validate パラメータが true に設定されたときの動作と同じです。

注: validate-if-schema と validate は相互に排他的です。一方を true に設定すると、他方は false に設定されます。

false
[必須] (デフォルト) ドキュメントにスキーマがある場合、内部サブセット処理を含め、スキーマ処理を行いません。デフォルトの属性値情報は維持されます。validate が true の場合は、引き続き検証が行われます。
"well-formed"
true
[必須] (デフォルト) すべてのノードが、Document.xmlVersion 属性で指定された使用中の XML バージョンに従う XML 整形式であることを次のようにチェックします。
  • Node.nodeName 属性がノードに対して無効な文字を含むかどうかをチェックし、必要に応じて DOMError.SEVERITY_ERROR 重要度を含む "wf-invalid-character-in-node-name" 型の DOMError を生成する
  • AttrElementCommentTextCDATASection ノード内のテキスト内容に無効な文字が含まれていないかどうかチェックし、必要に応じて DOMError.SEVERITY_ERROR 重要度を含む "wf-invalid-character" 型の DOMError を生成する
  • ProcessingInstruction ノード内のデータに無効な文字が含まれていないかどうかをチェックし、必要に応じて DOMError.SEVERITY_ERROR 重要度を含む "wf-invalid-character" 型の DOMError を生成する
false
[オプション] XML 整形性のチェックを行いません。

エンティティに関連するシステム識別子の解決は Document.documentURI を使って行われます。ただし、 DOM 実装が [DOM Level 3 Load および Save] で定義されている LS 機能をサポートする場合は、Document ノードに接続された DOMConfiguration オブジェクトで resource-resolver パラメータを使用することもできます。このパラメータを設定すると、Document.normalizeDocument()Document.documentURI を使用することなくリソース リゾルバを呼び出します。

「Document Object Model (DOM) Level 3 Core Specification」も参照してください。

導入されたバージョン:
DOM Level 3

メソッドの概要
 boolean canSetParameter(String name, Object value)
          パラメータを特定の値に設定できるかどうかをチェックします。
 Object getParameter(String name)
          既知の場合、パラメータの値を返します。
 DOMStringList getParameterNames()
          DOMConfiguration オブジェクトがサポートし、かつアプリケーションで少なくとも 1 つの値を設定できるパラメータのリスト。
 void setParameter(String name, Object value)
          パラメータの値を設定します。
 

メソッドの詳細

setParameter

void setParameter(String name,
                  Object value)
                  throws DOMException
パラメータの値を設定します。

パラメータ:
name - 設定するパラメータの名前
value - 新しい値。パラメータを設定しない場合は null。値パラメータの型が DOMUserData として定義されているかぎり、オブジェクト型はパラメータの定義で定義された型に一致しなければならない。たとえば、パラメータが error-handler の場合、値は DOMErrorHandler 型でなければならない
例外:
DOMException - NOT_FOUND_ERR: パラメータ名が認識されない場合に発生する
NOT_SUPPORTED_ERR: パラメータ名が認識されても要求された値に設定できない場合に発生する
TYPE_MISMATCH_ERR: このパラメータの値の型が想定された値の型と互換性がない場合に発生する

getParameter

Object getParameter(String name)
                    throws DOMException
既知の場合、パラメータの値を返します。

パラメータ:
name - パラメータの名前
戻り値:
指定されたパラメータに関連付けられた現在のオブジェクト。オブジェクトが関連付けられていない場合またはパラメータがサポートされていない場合は null
例外:
DOMException - NOT_FOUND_ERR: パラメータ名が認識されない場合に発生する

canSetParameter

boolean canSetParameter(String name,
                        Object value)
パラメータを特定の値に設定できるかどうかをチェックします。

パラメータ:
name - チェックするパラメータ名
value - オブジェクト。null の場合、true が返される
戻り値:
パラメータを指定された値に正常に設定できた場合は true。パラメータが認識されない場合または要求された値がサポートされていない場合は false。この場合、パラメータ自体の現在の値は変更されない

getParameterNames

DOMStringList getParameterNames()
DOMConfiguration オブジェクトがサポートし、かつアプリケーションで少なくとも 1 つの値を設定できるパラメータのリスト。このリストには、この仕様以外で定義されたパラメータ名を含めることもできます。


共通 DOM API

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