模块  java.xml
软件包  org.w3c.dom

Interface DOMConfiguration


  • public interface DOMConfiguration
    DOMConfiguration接口表示文档的配置并维护已识别参数的表。 使用上述结构,能够改变Document.normalizeDocument()行为,如更换CDATASection与节点Text节点或指定的验证时必须使用的模式的类型Document被请求。 DOMConfiguration对象也用于[ DOM Level 3 Load and Save ]的DOMParserDOMSerializer接口中。

    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.schemaTypeInfoAttr.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 (如有必要);
    • 检查,如果文本内容内AttrElementCommentTextCDATASection的无效字符节点,并生成一个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

    另见Document Object Model (DOM) Level 3 Core Specification

    从以下版本开始:
    1.5,DOM Level 3
    • 方法详细信息

      • 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 this DOMConfiguration 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.