Module java.xml

Package org.w3c.dom

Interface DOMConfiguration

       public interface DOMConfiguration
      

DOMConfiguration接口表示文档的配置，并维护一个已识别参数的表。使用配置，可以更改Document.normalizeDocument()的行为，例如用Text节点替换CDATASection节点或指定在请求验证Document时必须使用的模式类型。DOMConfiguration对象还在[DOM Level 3 Load and Save]中的DOMParser和DOMSerializer接口中使用。

DOMConfiguration对象使用的参数名称在整个DOM Level 3规范中定义。名称不区分大小写。为避免可能的冲突，作为约定，应使指向DOM规范之外定义的参数的名称唯一。因为参数作为属性公开，建议名称遵循[Unicode]第5.16节标识符，其中添加字符“-”（HYPHEN-MINUS），但DOM实现不强制执行。DOM Level 3 Core实现必须识别本规范中定义的所有参数。某些参数值可能也需要得到实现的支持。请参考参数的定义以了解值是否必须得到支持。

注意：参数类似于SAX2 [SAX]中使用的功能和属性。

以下是DOM中定义的参数列表：

"规范形式"

true

[可选] 根据[规范XML]中指定的规则对文档进行规范化，例如从树中删除DocumentType节点（如果有）或从每个元素中删除多余的命名空间声明。请注意，这仅限于DOM中可以表示的内容；特别是，无法指定DOM中属性的顺序。此外，将此参数设置为true还将设置下面列出的参数的状态。稍后对这些参数中任何一个的状态进行更改将会将"规范形式"恢复为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节点合并。

"检查字符规范化"

true

[可选] 检查文档中的字符是否完全规范化，如[XML 1.1]的附录B中定义的那样。当遇到未通过规范化检查的字符序列时，将发出一个DOMError.type等于"check-character-normalization-failure"的错误。

false

[必需]（默认）不检查字符是否规范化。

"注释"

true

[必需]（默认）保留文档中的Comment节点。

false

[必需]丢弃文档中的Comment节点。

"数据类型规范化"

true

[可选] 在树中公开模式规范化的值，例如在XML Schema的情况下XML Schema规范化值。由于此参数需要具有模式信息，因此"validate"参数也将设置为true。当"validate"为false时激活此参数将不会产生任何效果，也不会发生模式规范化。

注意:由于文档包含XML 1.0处理的结果，此参数不适用于第3.3.3节中定义的属性值规范化[XML 1.0]，仅适用于文档类型定义（DTD）之外的模式语言。

false

[必需]（默认）不对树执行模式规范化。

"元素内容空白"

true

[必需]（默认）保留文档中的所有空格。

false

[可选]丢弃元素内容中包含空格的所有Text节点，如[元素内容空白]中所述。实现预期使用属性Text.isElementContentWhitespace来确定是否应丢弃Text节点。

"实体"

true

[必需]（默认）保留文档中的EntityReference节点。

false

[必需]从文档中删除所有EntityReference节点，直接放置实体扩展。根据Node.normalize中定义的方式对Text节点进行规范化。仅保留文档中的未展开的实体引用。

注意:此参数不影响Entity节点。

"错误处理程序"

[必需] 包含一个DOMErrorHandler对象。如果在文档中遇到错误，实现将调用使用此参数注册的DOMErrorHandler。实现可能提供一个默认的DOMErrorHandler对象。调用时，DOMError.relatedData将包含发生错误的最接近节点。如果实现无法确定错误发生的节点，则DOMError.relatedData将包含Document节点。在错误处理程序内对文档的变更将导致实现相关的行为。

"信息集"

true

[必需]保留在XML信息集[XML信息集]中定义的信息。这将强制将以下参数设置为false：" validate-if-schema"、"entities"、"datatype-normalization"、"cdata-sections"。这将强制将以下参数设置为true：" namespace-declarations"、"well-formed"、"element-content-whitespace"、" comments"、"namespaces"。除非在参数描述中明确指定，否则不会更改其他参数。请注意，使用getParameter查询此参数只有在适当设置了上述各个参数时才会返回true。

false

将infoset设置为false不会产生任何效果。

"命名空间"

true

[必需]（默认）执行如下所定义的命名空间处理。

false

[可选] 不执行命名空间处理。

"命名空间声明"

如果参数"namespaces"设置为false，此参数将不起作用。

true

[必需]（默认）在文档中包含从模式中指定或默认的命名空间声明属性。另请参阅[XML命名空间]中的"声明命名空间"部分和[XML命名空间1.1]。

false

[必需]丢弃所有命名空间声明属性。即使将此参数设置为false，命名空间前缀（Node.prefix）仍保留。

"规范化字符"

true

[可选] 根据[XML 1.1]附录B中定义的方式对文档中的字符进行完全规范化。

false

[必需]（默认）不执行字符规范化。

"模式位置"

[可选] 表示包含由空格分隔的URI列表的DOMString对象（与第2.3节中定义的非终端生产S匹配的字符），表示应该进行验证的模式，即当前模式。此列表中引用的模式类型必须与使用schema-type指定的类型匹配，否则实现的行为是未定义的。使用此属性指定的模式优先于文档本身中指定的模式信息。对于命名空间感知模式，如果使用此属性指定的模式和文档实例中指定的模式（即使用schemaLocation属性）在模式文档中（即使用模式import机制）中共享相同的targetNamespace，则将使用由用户使用此属性指定的模式。如果两个使用此属性指定的模式共享相同的targetNamespace或没有命名空间，则行为是实现相关的。如果未提供位置，则此参数为null。

注意:除非设置了"schema-type"参数值，否则将忽略"schema-location"参数。强烈建议设置Document.documentURI，以便实现可以成功解析引用的任何外部实体。

"模式类型"

[可选] 表示包含绝对URI的DOMString对象，表示用于根据模式语言验证文档的模式语言的类型。请注意，对绝对URI不进行词法检查。如果未设置此参数，实现可能会根据支持的模式语言和加载时使用的模式语言提供默认值。如果未提供值，则此参数为null。

注意:对于XML Schema[XML Schema Part 1]，应用程序必须使用值"http://www.w3.org/2001/XMLSchema"。对于XML DTD[XML 1.0]，应用程序必须使用值"http://www.w3.org/TR/REC-xml"。其他模式语言超出W3C的范围，因此应推荐使用绝对URI以使用此方法。

"拆分CDATA部分"

true

[必需]（默认）拆分包含CDATA部分终止标记']]>'的CDATA部分。当拆分CDATA部分时，将发出一个警告，其中DOMError.type等于"cdata-sections-splitted"，DOMError.relatedData等于从拆分中得到的文档顺序中的第一个CDATASection节点。

false

[必需]如果CDATASection包含不可表示的字符，则发出错误。

"验证"

true

[可选] 要求对文档进行模式验证（例如XML模式、DTD、任何其他类型或表示模式），在文档被规范化时进行验证，如 [XML 1.0] 中定义。如果发现验证错误，或者未找到模式，则会通知错误处理程序。除非参数"datatype-normalization"为 true，否则不会根据使用的模式公开模式规范化的值。此参数将重新评估：

• 具有 Attr.specified 等于 false 的属性节点，如 Attr 接口的描述中所述；
• 所有 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 是否包含根据其节点类型的无效字符，并在必要时生成类型为 "wf-invalid-character-in-node-name" 的 DOMError，具有 DOMError.SEVERITY_ERROR 严重性；
• 检查 Attr、Element、Comment、Text、CDATASection 节点内部的文本内容是否包含无效字符，并在必要时生成类型为 "wf-invalid-character" 的 DOMError，具有 DOMError.SEVERITY_ERROR 严重性；
• 检查 ProcessingInstruction 节点内部的数据是否包含无效字符，并在必要时生成类型为 "wf-invalid-character" 的 DOMError，具有 DOMError.SEVERITY_ERROR 严重性；

false

[可选] 不检查XML格式是否正确。

与实体相关联的系统标识符的分辨率是使用Document.documentURI完成的。然而，当DOM实现支持[DOM Level 3 Load and Save]中定义的"LS"特性时，也可以在附加到Document节点的DOMConfiguration对象上使用参数"resource-resolver"。如果设置了此参数，Document.normalizeDocument()将调用资源解析器，而不是使用Document.documentURI。

另请参阅文档对象模型（DOM）Level 3 Core规范。

自从:

1.5, DOM Level 3

Method Summary

Modifier and Type	Method	Description
boolean	canSetParameter(String name, Object value)	检查是否支持将参数设置为特定值。
Object	getParameter(String name)	如果已知，返回参数的值。
DOMStringList	getParameterNames()	此DOMConfiguration对象支持的参数列表，应用程序可以设置其中至少一个值。
void	setParameter(String name, Object value)	设置参数的值。

Method Details

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对象支持的参数列表，应用程序可以设置其中至少一个值。请注意，此列表还可以包含在本规范之外定义的参数名称。