org.w3c.dom

インタフェース DOMConfiguration

public interface DOMConfiguration

DOMConfiguration インタフェースは文書の構成を表し、認められているパラメータのテーブルを保持します。この構成を使用すると、CDATASection ノードの Text ノードへの置き換えや、Document の検証が要求されたときに使用する必要のあるスキーマの型の指定などの Document.normalizeDocument() の動作を変更できます。DOMConfiguration オブジェクトはまた、DOMParser インタフェースや DOMSerializer インタフェース内の「DOM Level 3 Load and Save」でも使用されます。

DOMConfiguration オブジェクトによって使用されるパラメータ名は、DOM Level 3 仕様全体にわたって定義されています。名前は大文字と小文字が区別されます。コンフリクトを避けるため、規則として、DOM 仕様の範囲外で定義されたパラメータを参照する名前は一意にする必要があります。パラメータはプロパティーとして公開されるので、名前は、追加の文字「-」(HYPHEN-MINUS) を含む「Unicode」のセクション 5.16「識別子」に従うことをお勧めしますが、DOM 実装により強制はされません。DOM レベル 3 コア実装では、この仕様で定義されているすべてのパラメータを認識する必要があります。一部のパラメータ値も、この実装でサポートされる必要があります。値がサポートされているかどうかについては、パラメータの定義を参照してください。

注: パラメータは、SAX2「SAX」で使用される機能およびプロパティーと同様です。

次のパラメータリストは DOM で定義されています。

"canonical-form"

true

[オプション] ツリーから DocumentType ノード (存在する場合) を削除したり、各要素から余分な名前空間宣言を削除したりするなど、「正規 XML」で指定されている規則に従って文書を正規化します。これは DOM で表現できるコンテンツに制限されます。特に、DOM で属性の順序を指定する方法はありません。さらに、このパラメータを true に設定すると、下記のパラメータの状態も設定されます。あとで、これらのいずれかのパラメータの状態を変更すると、「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 で定義されているように、完全に正規化されているかどうかを確認します。正規化チェックに失敗した文字シーケンスが検出された場合は、DOMError.type が「check-character-normalization-failure」に等しいエラーが発行されます。

false

[必須] (デフォルト) 文字が正規化されているかどうかを確認しません。

"comments"

true

[必須] (デフォルト) 文書の Comment ノードを維持します。

false

[必須] 文書内の Comment ノードを破棄します。

"datatype-normalization"

true

[オプション] XML スキーマの場合の XML スキーマ正規化値などの、ツリー内のスキーマ正規化値を公開します。このパラメータにはスキーマ情報が含まれている必要があるため、「validate」パラメータも true に設定されます。「validate」が false のときにこのパラメータをアクティブにしても効果はなく、スキーマの正規化は行われません。

注: 文書は XML 1.0 処理の結果を含んでいるので、このパラメータは、「XML 1.0」のセクション 3.3.3 で定義されている属性値正規化には適用されず、文書型定義 (DTD) 以外のスキーマ言語だけを対象にしています。

false

[必須] (デフォルト) ツリー上でスキーマの正規化を実行しません。

"element-content-whitespace"

true

[必須] (デフォルト) 文書内のすべての空白文字を維持します。

false

[オプション] 「要素コンテンツの空白文字」で説明されている、要素コンテンツ内に空白文字を含むすべての Text ノードを破棄します。実装では、Text.isElementContentWhitespace 属性を使用して、Text ノードを破棄する必要があるかどうかを判定することが求められます。

"entities"

true

[必須] (デフォルト) 文書の EntityReference ノードを維持します。

false

[必須] 文書からすべての EntityReference ノードを削除し、その場所で直接エンティティー拡張を行います。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

infoset を false に設定しても効果はありません。

"namespaces"

true

[必須] (デフォルト) 定義に従って、名前空間処理を実行します。

false

[オプション] 名前空間処理を実行しません。

"namespace-declarations"

「namespaces」パラメータが false に設定されている場合、このパラメータは効果がありません。

true

[必須] (デフォルト) スキーマから指定またはデフォルト設定されている名前空間宣言属性を文書内に含めます。「XML 名前空間」と「XML 名前空間 1.1」の「名前空間の宣言」セクションも参照してください。

false

[必須] すべての名前空間宣言属性を破棄します。このパラメータが false に設定されていても、名前空間接頭辞 (Node.prefix) は保持されます。

"normalize-characters"

true

[オプション] 「XML 1.1」の付録 B で定義されているように、文書内の文字を完全に正規化します。

false

[必須] (デフォルト) 文字の正規化を実行しません。

"schema-location"

[オプション] 空白文字 (「XML 1.0」のセクション 2.3 で定義されている非終端生成 S に一致する文字) で区切られた URI のリストを含む DOMString オブジェクトを表します。このオブジェクトは、検証が行われるスキーマ (現在のスキーマ) を表します。このリストで参照されるスキーマの型は、schema-type で指定された型に一致しなければいけません。一致しない場合、実装の動作は保証されません。このプロパティーを使用して指定されたスキーマは、文書で独自に指定されたスキーマ情報より優先されます。名前空間認識スキーマの場合、このプロパティーで指定されたスキーマと、スキーマドキュメント (スキーマ import メカニズムを使用) のドキュメントインスタンス (schemaLocation 属性を使用) で指定されたスキーマが同じ targetNamespace を共有するとき、ユーザーがこのプロパティーを使用して指定したスキーマが使用されます。このプロパティーを使用して指定された 2 つのスキーマが、同じ targetNamespace を共有するか、名前空間を持たない場合、動作は実装に依存して決まります。場所を指定しなかった場合、このパラメータは null になります。

注: 「schema-type」パラメータ値が設定されていないかぎり、"schema-location" パラメータは無視されます。参照されたすべての外部エンティティーを実装で正常に解決できるように、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" に等しく、DOMError.relatedData が分割の結果として得られた文書順で最初の CDATASection ノードに等しい警告が発行されます。

false

[必須] CDATASection に表現できない文字が含まれている場合に、エラーを通知します。

"validate"

true

[オプション] 「XML 1.0」によって定義されているように正規化されている文書のスキーマ (つまり、XML スキーマ、DTD、スキーマのその他の任意の型または表現) に対する検証を必要とします。検証エラーが見つかったり、スキーマが見つからなかったりした場合は、エラーハンドラに通知されます。スキーマ正規化値は、「datatype-normalization」パラメータが true でないかぎり、使用されているスキーマに従って公開されません。このパラメータは、次のものを再評価します。

• Attr インタフェースの説明で指定されているように、Attr.specified が false に等しい属性ノード。
• すべての 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 を生成します。
• Attr、Element、Comment、Text、CDATASection の各ノード内のテキストコンテンツに無効な文字が含まれているかどうかを確認し、必要に応じて、重要度が DOMError.SEVERITY_ERROR で、型が "wf-invalid-character" の DOMError を生成します。
• ProcessingInstruction ノード内のデータに無効な文字が含まれているかどうかを確認し、必要に応じて、重要度が DOMError.SEVERITY_ERROR で、型が "wf-invalid-character" の DOMError を生成します。

false

[オプション] XML の整形式をチェックしません。

エンティティーに関連付けられシステム識別子の解決は、Document.documentURI を使用して実行されます。ただし、「DOM Level 3 Load and Save」で定義されている「LS」機能が DOM 実装でサポートされている場合は、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。value パラメータの型は 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 つの値をこれらのパラメータに対して設定できます。このリストには、この仕様の外部で定義されたパラメータ名も含まれる可能性があります。