org.w3c.dom

接口
异常

org.w3c.dom
接口 DOMConfiguration

public interface DOMConfiguration

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

由 DOMConfiguration 对象使用的参数名称可在整个 DOM Level 3 规范中定义。名称不区分大小写。要避免可能的冲突，根据惯例，应该使指向在 DOM 规范之外定义的参数的名称唯一。因为参数要作为属性公开，所以建议名称遵循 5.16 节带有字符 '-'（连字符号）的“[Unicode] 标识符”，但它不是由 DOM 实现强制执行的。要求 DOM Level 3 核心实现来识别在此规范中定义的所有参数。也可能要求某些参数值接受该实现的支持。若要知道一个值是否必须被支持，请参阅参数的定义。

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

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

"canonical-form"
true
[ optional] 根据在 [ Canonical 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 节点合并起来。
"check-character-normalization"
true
[ 可选] 检查文档中的字符是否是 完全规范化，如在 [ XML 1.1] 的附录 B 中定义的那样。当遇到规范化检查失败的字符序列时，将发生带有 DOMError.type（等于 "check-character-normalization-failure"）的错误。
false
[ 需要]（ 默认）不检查字符是否规范化。
"comments"
true
[ 需要]（ 默认）保留文档中的 Comment 节点。
false
[ 需要]丢弃文档中的 Comment 节点。
"datatype-normalization"
true
[ optional] 公开树中的模式标准化值，如 XML 模式中的 XML 模式标准化值。由于此参数要求有模式信息，所以还要将 "validate" 参数设置为 true。"validate" 为 false 时激活此参数无效，且不发生模式规范化。

注：由于文档包含 XML 1.0 处理的结果，所以此参数不会像在 [XML 1.0] 的 3.3.3 节中定义的那样应用于属性值规范化，而只用于除文档类型定义 (DTD) 之外的模式语言。

false
[ 需要]（ 默认）不执行对树的模式规范化。
"element-content-whitespace"
true
[ 需要]（ 默认）保留文档中的所有空格。
false
[ 可选] 丢弃在元素内容中包含空格的所有 Text 节点，如在 [element content whitespace] 中描述的那样。期望该实现使用属性 Text.isElementContentWhitespace 来确定是否应该丢弃 Text 节点。
"entities"
true
[ 需要]（ 默认）保留文档中的 EntityReference 节点。
false
[ 需要] 从文档中移除所有 EntityReference 节点，并直接将实体扩展放入适当位置。按 Node.normalize 中定义的那样，标准化 Text 节点。文档中只保留 未扩展的实体引用。

注：此参数不影响 Entity 节点。

"error-handler"
[ 需要] 包含 DOMErrorHandler 对象。如果在文档中遇到错误，则该实现将回调使用此参数注册的 DOMErrorHandler。该实现可以提供默认的 DOMErrorHandler 对象。调用时， DOMError.relatedData 将包含离发生错误的位置最近的节点。如果该实现不能确定发生错误的节点，则 DOMError.relatedData 将包含 Document 节点。从错误处理程序内部对文档的修改将导致与实现有关的行为。
"infoset"
true
[ 需要] 在文档中保留在 XML 信息集合 [ XML Information Set] 中定义的信息。这样做强迫以下参数为 false："validate-if-schema"、"entities"、"datatype-normalization"、"cdata-sections"。这迫使以下参数为 true："namespace-declarations"、"well-formed"、"element-content-whitespace"、" comments"、"namespaces"。其他参数只有在参数的描述中显式指定时才能更改。注意，只有在适当设置以上指定的单个参数时，使用 getParameter 查询此参数才能返回 true。
false
将 infoset 设置为 false 无效。
"namespaces"
true
[ 需要]（ 默认）按以下定义方式执行名称空间处理。
false
[ 可选] 不执行名称空间处理。
"namespace-declarations"
如果将参数 "namespaces" 设置为 false，则此参数无效。
true
[ 需要]（ 默认）包括在文档中模式指定或默认的名称空间声明属性。另请参见 [ XML Namespaces] 和 [ XML Namespaces 1.1] 中的“声明名称空间”各节。
false
[ 需要] 丢弃所有名称空间声明属性。保留名称空间前缀 ( Node.prefix)，即使此参数设置为 false。
"normalize-characters"
true
[ 可选] 完全标准化文档中的字符，如 [ XML 1.1] 的附录 B 中定义的那样。
false
[ 需要]（ 默认）不执行字符规范化。
"schema-location"
[ 可选] 表示包含 URI 列表的 DOMString 对象，由空格分隔（与在 [ XML 1.0] 第 2.3 节定义的 nonterminal production S 匹配的字符），它表示对其进行验证的模式，即当前模式。此列表中引用的模式类型必须匹配用 schema-type 指定的类型，否则实现的行为不确定。使用此属性指定的模式优先于在文档本身中指定的模式信息。对于名称空间感知的模式而言，如果使用此属性指定的模式和模式文档（例如使用 schemaLocation 属性）中在文档实例中（例如使用模式 import 机制）指定的模式共享同一 targetNamespace，则将使用由用户使用此属性指定的模式。如果使用此属性指定的两个模式共享同一 targetNamespace，或不存在名称空间，则该行为与实现有关。如果未提供任何位置，则此参数为 null。

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

"schema-type"
[ 可选] 表示一个 DOMString 对象，该对象包含绝对 URI 且表示用于对其验证文档的模式语言类型。注意，不对绝对 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.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 或模式的任何其他类型或表示形式）中找到文档元素的声明时启用验证。如果启用验证，则此参数的行为与设置为 true 的参数 "validate" 的行为相同。

注："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 severity）；
  • 检查 Attr、Element、Comment、Text、CDATASection 节点内的文本内容是否包含无效字符，是否生成类型 "wf-invalid-character" 的 DOMError（必要时带有 DOMError.SEVERITY_ERROR severity）；
  • 检查 ProcessingInstruction 节点内的数据是否包含无效字符，是否生成类型 "wf-invalid-character" 的 DOMError（必要时带有 DOMError.SEVERITY_ERROR severity）；
false
[ 可选] 不检查 XML 的格式良好性。

使用 Document.documentURI 解析与实体相关的系统标识符。但是，当 DOM 实现支持在 [DOM Level 3 Load and Save] 中定义的功能 "LS" 时，参数 "resource-resolver" 还可以在连接到 Document 节点的 DOMConfiguration 上使用。如果已设置了此参数，则 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 对象支持的参数列表，并且应用程序至少可以为其设置一个值。
 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 对象支持的参数列表，并且应用程序至少可以为其设置一个值。注意，此列表还可以包含在此规范之外定义的参数名称。