Module  java.xml
软件包  org.w3c.dom

Interface DOMConfiguration



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

    DOMConfiguration对象使用的参数名称定义在DOM Level 3规范中。 名称不区分大小写。 为了避免可能的冲突,作为惯例,引用在DOM规范之外定义的参数的名称应该是唯一的。 因为参数是公开的,因为名称中的属性建议遵循5.16标识符[Unicode],添加字符' - '(HYPHEN-MINUS),但不被DOM实现强制执行。 DOM 3级核心实现需要识别本规范中定义的所有参数。 某些参数值也可能需要由实现支持。 参考参数的定义来知道是否必须支持一个值。

    注意:参数类似于SAX2 [ SAX ]中使用的特征和属性。

    DOM中定义的以下参数列表:

    "canonical-form"
    true
    [ 可选 ]根据[ Canonical XML ]中规定的规则对文档进行规范化,例如从树中删除DocumentType节点(如果有),或从每个元素中删除多余的命名空间声明。 请注意,这仅限于DOM中可以表示的内容; 特别是没有办法在DOM中指定属性的顺序。 另外,将此参数设置为true还将设置下列参数的状态。 对这些参数之一的状态的更改将会将“规范形式”恢复为false 参数设置为false :“entities”,“normalize-characters”,“cdata-sections”。 参数设置为true :“namespaces”,“namespace-declaration”,“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 当“验证”为false时激活此参数没有任何效果,并且不会发生模式归一化。

    注意:由于文档包含XML 1.0处理的结果,该参数不适用于[ XML 1.0 ]第3.3.3节中定义的属性值归一化,仅适用于文档类型定义(DTD)以外的模式语言。

    false
    [ 必需 ]( 默认 )不要在树上执行模式归一化。
    "element-content-whitespace"
    true
    [ 必需 ]( 默认 )将所有空格保留在文档中。
    false
    [ 可选 ]如[element content whitespace]所述,放弃包含元素内容中的空格的所有Text节点。 预期实现使用属性Text.isElementContentWhitespace来确定是否应丢弃Text节点。
    "entities"
    true
    [ 必需 ]( 默认 )在文档中保留EntityReference节点。
    false
    [ 必需 ]从文档中删除所有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-declaration”,“well-formed”,“element-content-whitespace”,“comments”,“namespaces”。其他参数不会更改,除非在参数。 请注意,仅当上述指定的各个参数被适当设置时,使用getParameter查询此参数getParameter返回true
    false
    设置infosetfalse没有任何效果。
    "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-location"参数被忽略,除非设置了“模式类型”参数值。 强烈建议设置Document.documentURI以便一个实现可以成功地解析引用的任何外部实体。

    "schema-type"
    [ 可选 ]表示包含绝对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部分被拆"cdata-sections-splitted" ,发出警告,其中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 Attr ;
    • 属性Element.schemaTypeInfoAttr.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
    [ 必需 ]( 默认 )根据所使用的XML版本,检查所有节点是否格式良好, Document.xmlVersion
    • 根据其节点类型检查属性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”时,参数“资源解析器”也可以在连接到Document节点的DOMConfiguration对象上使用。 如果设置了此参数,则Document.normalizeDocument()将调用资源解析器,而不是使用Document.documentURI

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

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

      • setParameter

        void setParameter​(String name,
                          Object value)
                   throws DOMException
        设置参数的值。
        参数
        name - 要设置的参数的名称。
        value - 新值或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.