模块 java.xml

包 org.w3c.dom

接口 DOMConfiguration

public interface DOMConfiguration
      

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

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

笔记：参数类似于 SAX2 [SAX] 中使用的特性和属性。

DOM 中定义的参数列表如下：

"canonical-form"

true

[optional ] 根据 [规范的 XML ] 中指定的规则对文档进行规范化，例如从树中删除 DocumentType 节点（如果有），或从每个元素中删除多余的名称空间声明。请注意，这仅限于可以在 DOM 中表示的内容；特别是，没有办法指定属性在 DOM 中的顺序。此外，将此参数设置为true 还将设置下面列出的参数的状态。稍后对其中一个参数状态的更改会将“规范形式”恢复为 false 。设置为 false 的参数：“实体”、“标准化字符”、“cdata 部分”。设置为 true 的参数：“命名空间”、“命名空间声明”、“格式良好”、“元素内容空白”。除非在参数说明中明确指定，否则不会更改其他参数。

false

[required ] (default )不规范化文档。

"cdata-sections"

true

[required ] (default )在文档中保留CDATASection个节点。

false

[required ]将文档中的CDATASection个节点转化为Text个节点。然后将新的 Text 节点与任何相邻的 Text 节点组合。

"check-character-normalization"

true

[optional ] 检查文档中的字符是否为 完全归一化 ，如 [XML 1.1 ] 的附录 B 中所定义。当遇到规范化检查失败的字符序列时，将发出 DOMError.type 等于“check-character-normalization-failure”的错误。

false

[required ] (default )不检查字符是否规范化。

"comments"

true

[required ] (default )在文档中保留Comment个节点。

false

[required ]丢弃文档中的 Comment 个节点。

"datatype-normalization"

true

[optional ] 在树中公开模式规范化值，例如 XML 模式中的 XML 架构规范化值。由于此参数需要有架构信息，因此“validate”参数也将设置为 true 。当“验证”为 false 时激活此参数无效，并且不会发生模式规范化。

笔记：由于文档包含 XML 1.0 处理的结果，因此此参数不适用于 [XML 1.0] 第 3.3.3 节中定义的属性值规范化，并且仅适用于文档类型定义 (DTD) 以外的模式语言。

false

[required ] (default ) 不要对树执行模式规范化。

"element-content-whitespace"

true

[required ] (default )保留文档中的所有空格。

false

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

"entities"

true

[required ] (default )在文档中保留EntityReference个节点。

false

[required ] 从文档中删除所有 EntityReference 节点，将实体扩展直接放在它们的位置。 Text 节点已标准化，如 Node.normalize 中所定义。文档中只保留未展开的实体引用。

笔记：此参数不影响 Entity 个节点。

"error-handler"

[required ] 包含一个 DOMErrorHandler 对象。如果在文档中遇到错误，实现将回调使用此参数注册的DOMErrorHandler。该实现可能会提供一个默认的 DOMErrorHandler 对象。调用时，DOMError.relatedData 将包含距离发生错误的位置最近的节点。如果实现无法确定发生错误的节点，DOMError.relatedData 将包含 Document 节点。从错误处理程序中对文档的更改将导致依赖于实现的行为。

"infoset"

true

[required]在文档中保留 XML 信息集 [XML 信息集] 中定义的信息。这会强制将以下参数设置为 false：“validate-if-schema”、“entities”、“datatype-normalization”、“cdata-sections” .这将以下参数强制为true：“命名空间声明”、“格式良好”、“元素内容空白”、“评论”、“命名空间”。除非在描述中明确指定，否则不会更改其他参数参数。请注意，仅当正确设置了上面指定的各个参数时，使用 getParameter 查询此参数才会返回 true。

false

将 infoset 设置为 false 无效。

"namespaces"

true

[required ] (default ) 执行中定义的命名空间处理。

false

[optional ] 不执行名称空间处理。

"namespace-declarations"

如果参数“命名空间”设置为 false，则此参数无效。

true

[required ] (default ) 在文档中包含命名空间声明属性，这些属性是从模式中指定或默认的。另请参阅 [XML 命名空间 ] 和 [XML 命名空间 1.1 ] 中的“声明命名空间”部分。

false

[required ]丢弃所有名称空间声明属性。即使此参数设置为 false，命名空间前缀 (Node.prefix) 也会保留。

"normalize-characters"

true

[optional ] 完全归一化 [XML 1.1] 的附录 B 中定义的文档中的字符。

false

[required ] (default )不执行字符规范化。

"schema-location"

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

笔记："schema-location" 参数将被忽略，除非设置了“schema-type”参数值。强烈建议设置 Document.documentURI，以便实现可以成功解析引用的任何外部实体。

"schema-type"

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

笔记：对于 XML 架构 [XML 架构第 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

[required ] (default )拆分包含 CDATA 部分终止标记“]]>”的 CDATA 部分。当拆分 CDATA 部分时，将发出警告，其中 DOMError.type 等于 "cdata-sections-splitted" 且 DOMError.relatedData 等于拆分产生的文档顺序中的第一个 CDATASection 节点。

false

[required ]如果 CDATASection 包含无法表示的字符，则发出错误信号。

"validate"

true

[optional ] 需要根据文档的模式（即 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 。在验证文档时，应用程序还应考虑将参数“格式良好”设置为 true ，这是该选项的默认值。

false

[required ] (default ) 不完成模式处理，包括内部子集处理。保留默认属性值信息。请注意，如果“validate-if-schema”是 true ，验证可能仍会发生。

"validate-if-schema"

true

[optional ]仅当可以在模式中找到文档元素的声明时才启用验证（独立于找到它的位置，即 XML 模式、DTD 或模式的任何其他类型或表示）。如果启用验证，此参数与参数“validate”设置为 true 的行为相同。

笔记：“validate-if-schema”和“validate”是互斥的，将其中一个设置为 true 会将另一个设置为 false 。

false

[required ] (default ) 如果文档具有架构，则不应执行架构处理，包括内部子集处理。保留默认属性值信息。请注意，如果“validate”为 true ，则仍必须进行验证。

"well-formed"

true

[required ] (default ) 根据 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

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

与实体关联的系统标识符的解析是使用 Document.documentURI 完成的。但是，当 DOM 实现支持 [DOM Level 3 加载和保存] 中定义的功能“LS”时，参数“resource-resolver”也可以用于附加到 Document 节点的 DOMConfiguration 对象。如果设置了此参数，Document.normalizeDocument() 将调用资源解析器而不是使用 Document.documentURI。

另见 文档对象模型 (DOM) 级别 3 核心规范 。

自从：

1.5，DOM 级别 3

方法总结

修饰符和类型	方法	描述
boolean	canSetParameter(String name, Object value)	检查是否支持将参数设置为特定值。
Object	getParameter(String name)	如果已知，则返回参数的值。
DOMStringList	getParameterNames()	此 DOMConfiguration 对象支持的参数列表，应用程序至少可以为其设置一个值。
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 对象支持的参数列表，应用程序至少可以为其设置一个值。请注意，此list还可以包含在本规范之外定义的参数名称。