-
public interface DOMConfiguration
DOMConfiguration
接口表示文档的配置并维护已识别参数的表。 使用上述结构,能够改变Document.normalizeDocument()
行为,如更换CDATASection
与节点Text
节点或指定的验证时必须使用的模式的类型Document
被请求。DOMConfiguration
对象也用于[ DOM Level 3 Load and Save ]的DOMParser
和DOMSerializer
接口中。DOMConfiguration
对象使用的参数名称在DOM Level 3规范中定义。 名称不区分大小写。 为了避免可能的冲突,作为约定,引用DOM规范之外定义的参数的名称应该是唯一的。 因为参数是作为名称中的属性公开的,所以建议遵循5.16 [Unicode]的标识符,并添加字符' - '(HYPHEN-MINUS),但DOM实现不强制执行。 DOM Level 3核心实现需要识别本规范中定义的所有参数。 实现还可能需要某些参数值。 请参阅参数的定义以了解是否必须支持值。注意:参数类似于SAX2 [ SAX ]中使用的特征和属性。
DOM中定义的以下参数列表:
-
"canonical-form"
-
-
true
-
[ 可选 ]根据[ 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
-
[ 可选 ]检查文档中的字符是否为fully normalized ,如[ XML 1.1 ]附录B中所定义。
当遇到未通过规范化检查的字符序列时,将
DOMError.type
等于“check-character-normalization-failure”的错误。 -
false
- [ 必填 ]( 默认 )不检查字符是否规范化。
-
-
"comments"
-
-
true
-
[ 必需 ]( 默认 )在文档中保留
Comment
节点。 -
false
-
[ required ]丢弃文档中的
Comment
节点。
-
-
"datatype-normalization"
-
-
true
-
[ 可选 ]在树中公开模式规范化值,例如在XML Schema的情况下为XML Schema normalized values 。
由于此参数需要具有架构信息,因此“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
-
[ required ]从文档中删除所有
EntityReference
节点,将实体扩展直接放在其位置。Text
节点已标准化,如Node.normalize
所定义。 文档中仅保留了unexpanded entity references 。
注意:此参数不会影响
Entity
节点。 -
-
"error-handler"
-
[ 必需 ]包含
DOMErrorHandler
对象。 如果文档中遇到错误,实现将回调使用此参数注册的DOMErrorHandler
。 该实现可以提供默认的DOMErrorHandler
对象。 调用时,DOMError.relatedData
将包含发生错误的最近节点。 如果实现无法确定发生错误的节点,则DOMError.relatedData
将包含Document
节点。 从错误处理程序中对文档的突变将导致依赖于实现的行为。 -
"infoset"
-
-
true
-
[ required ]在文档中保留XML信息集[ XML Information Set ]中定义的信息。这会强制以下参数为
false
:“validate-if-schema”,“entities”,“datatype-normalization”,“cdata-sections” 。这强制以下参数为true
:“namespace-declarations”,“格式良好”,“element-content-whitespace”,“comments”,“namespaces”。除非在描述中明确指定,否则不更改其他参数参数。 请注意,仅当适当设置了上面指定的各个参数时,使用getParameter
查询此参数getParameter
返回true
。 -
false
-
将
infoset
设置为false
无效。
-
-
"namespaces"
-
-
true
- [ 必需 ]( 默认 )按照中的定义执行命名空间处理。
-
false
- [ 可选 ]不执行命名空间处理。
-
-
"namespace-declarations"
-
如果参数“namespaces”设置为
false
则此参数false
。-
true
- [ 必需 ]( 默认 )在文档中包含从模式中指定或默认的名称空间声明属性。 另请参见[ XML Namespaces ]和[ XML Namespaces 1.1 ]中的“声明命名空间”部分。
-
false
-
[ required ]放弃所有名称空间声明属性。
即使此参数设置为
false
也会保留名称空间前缀(Node.prefix
)。
-
-
"normalize-characters"
-
-
true
- [ 可选 ] Fully normalized文档中的字符,如[ XML 1.1 ]附录B中所定义。
-
false
- [ 必需 ]( 默认 )不执行字符规范化。
-
-
"schema-location"
-
[ 可选 ]表示包含URI列表的
DOMString
对象,由空格分隔(与第2.3节[ XML 1.0 ]中定义的nonterminal production S匹配的字符),表示应进行验证的模式,即当前模式。 此列表中引用的模式类型必须与使用schema-type
指定的类型匹配,否则实现的行为未定义。 使用此属性指定的模式优先于文档本身中指定的模式信息。 对于名称空间感知的模式而言,如果使用此属性,并在文件实例(即使用指定模式指定模式schemaLocation
属性)架构文档中(例如使用模式import
机制)共享同一targetNamespace
,使用由用户指定的模式将使用此属性。 如果使用此属性指定的两个模式共享相同的targetNamespace
或没有命名空间,则该行为取决于实现。 如果未提供任何位置,则此参数为null
。注意:除非设置了“schema-type”参数值,否则将忽略
"schema-location"
参数。 强烈建议设置Document.documentURI
以便实现可以成功解析所引用的任何外部实体。 -
"schema-type"
-
[ optional ]表示包含绝对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以使用此方法。 -
"split-cdata-sections"
-
-
true
-
[ 必需 ]( 默认 )拆分包含CDATA部分终止标记']]>'的CDATA部分。
当CDATA部被分割与发出警告
DOMError.type
等于"cdata-sections-splitted"
和DOMError.relatedData
等于第一CDATASection
节点按文档顺序从分割得到的。 -
false
-
[ required ]如果
CDATASection
包含不可表示的字符,则表示错误。
-
-
"validate"
-
-
true
-
[ 可选 ]要求对文档的模式(即XML模式,DTD,任何其他类型或模式表示)进行验证,因为它正在按照[ XML 1.0 ]的定义进行规范化。
如果找到验证错误,或者未找到架构,则会通知错误处理程序。
除非参数“datatype-normalization”为
true
否则将不会根据使用的模式公开模式规范化值。 此参数将重新评估:- 具有
Attr.specified
属性节点等于false
,如Attr
接口的描述中所指定的; - 该属性的值
Text.isElementContentWhitespace
所有Text
节点; - 该属性的值
Attr.isId
所有Attr
节点; - 字段
Element.schemaTypeInfo
和Attr.schemaTypeInfo
。
注意: “validate-if-schema”和“validate”是互斥的,将其中一个设置为
true
会将另一个设置为false
。 在验证文档时,应用程序还应考虑将参数“格式良好”设置为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版本检查所有节点是否格式良好:- 根据节点类型检查属性
Node.nodeName
包含无效字符,并生成类型为DOMError
的"wf-invalid-character-in-node-name"
,严重性为DOMError.SEVERITY_ERROR
(如有必要); - 检查,如果文本内容内
Attr
,Element
,Comment
,Text
,CDATASection
的无效字符节点,并生成一个DOMError
类型的"wf-invalid-character"
,具有DOMError.SEVERITY_ERROR
严重程度,如果必要的话; - 检查
ProcessingInstruction
节点内的数据ProcessingInstruction
为无效字符,并生成DOMError
类型为"wf-invalid-character"
,具有DOMError.SEVERITY_ERROR
严重性,必要时;
- 根据节点类型检查属性
-
false
- [ 可选 ]不检查XML格式是否正确。
-
与实体关联的系统标识符的解析使用
Document.documentURI
完成。 但是,当DOM实现支持[ DOM Level 3 Load and Save ]中定义的功能“LS”时,参数“resource-resolver”也可用于附加到Document
节点的DOMConfiguration
对象。 如果设置了此参数,则Document.normalizeDocument()
将调用资源解析程序而不是使用Document.documentURI
。- 从以下版本开始:
- 1.5,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
新值或null
。 虽然value参数的类型定义为DOMUserData
,但对象类型必须与参数定义定义的类型匹配。 例如,如果参数为“error-handler”,则该值必须为类型DOMErrorHandler
。 - 异常
-
DOMException
- NOT_FOUND_ERR:无法识别参数名称时DOMException
。
NOT_SUPPORTED_ERR:识别参数名称但无法设置请求的值时触发。
TYPE_MISMATCH_ERR:如果此参数名称的值类型与期望值类型不兼容,则引发此异常。
-
getParameter
Object getParameter(String name) throws DOMException
如果已知,则返回参数的值。- 参数
-
name
- 参数的名称。 - 结果
-
与指定参数关联的当前对象,如果没有关联对象或者不支持该参数,则为
null
。 - 异常
-
DOMException
- NOT_FOUND_ERR:无法识别参数名称时DOMException
。
-
canSetParameter
boolean canSetParameter(String name, Object value)
检查是否支持将参数设置为特定值。- 参数
-
name
- 要检查的参数的名称。 -
value
- 一个对象。 如果是null
,则返回值为true
。 - 结果
-
true
如果参数可以成功设置为指定值,false
如果未识别参数或不支持请求的值)。 这不会更改参数本身的当前值。
-
getParameterNames
DOMStringList getParameterNames()
The list of the parameters supported by thisDOMConfiguration
object and for which at least one value can be set by the application. Note that this list can also contain parameter names defined outside this specification.
-
-