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

Interface LSParser


  • public interface LSParser
    对象的接口,能够从各种输入源构建或扩充DOM树。

    LSParser提供了用于解析XML和构建相应DOM文档结构的API。 可以通过调用DOMImplementationLS.createLSParser()方法获得LSParser实例。

    如[ DOM Level 3 Core ]中所述,当文档首次通过LSParser提供时:

    • 永远不会有两个NODE_TEXT类型的相邻节点,永远不会有空文本节点。
    • 预计Attr节点的valuenodeValue属性最初返回XML 1.0 normalized value 但是,如果参数“ validate-if-schema ”和“ datatype-normalization ”设置为true ,则根据所使用的属性规范化,属性值可能与XML 1.0属性规范化获得的属性值不同。 如果参数“ datatype-normalization ”设置为false ,则保证发生XML 1.0属性规范化,如果属性列表不包含命名空间声明,则Element节点上的attributes属性表示[ XML Information Set ]中定义的属性[attributes ]。

    期望异步LSParser对象也实现events::EventTarget接口,以便可以在异步LSParser对象上注册事件侦听器。

    异步LSParser对象支持的事件是:

    加载
    LSParser完成加载文档。 另请参见LSLoadEvent接口的定义。
    进展
    LSParser在解析数据时LSParser信号。 此规范不会尝试准确定义何时应分派进度事件。 故意将其视为依赖于实现的。 以下是应用程序如何分派进度事件的一个示例:解析器开始接收数据后,将调度progress事件以指示解析开始。 从那里开始,为每个接收和处理的4096个字节的数据调度progress事件。 这只是一个例子,实现可以选择在解析时随时调度进度事件,或者根本不调度它们。 另请参见LSProgressEvent接口的定义。

    注意:本规范中定义的所有事件都使用名称空间URI "http://www.w3.org/2002/DOMLS"

    解析输入源时,会通过错误处理程序( LSParser.domConfig的“ error-handler ”参数)向应用程序报告错误。 此规范绝不会尝试定义解析XML或任何其他标记时可能发生的所有可能错误,但会定义一些常见错误情况。 本规范定义的错误和警告类型( DOMError.type )为:

    "check-character-normalization-failure" [error]
    如果参数“ check-character-normalization ”设置为true并且遇到未通过规范化检查的字符串,则引发此异常。
    "doctype-not-allowed" [fatal]
    如果配置参数“disallow-doctype”设置为true并且遇到doctype,则true
    "no-input-specified" [fatal]
    加载文档时LSInput并且未在LSInput对象中指定输入。
    "pi-base-uri-not-preserved" [warning]
    如果在无法保留处理指令的基URI的位置遇到处理指令,则引发。 引发此警告的一个示例是,如果配置参数“ entities ”设置为false并且解析了以下XML文件:
      <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]>
     <root> &e; </root> 
    并且subdir/myentity.ent包含:
      <one> <two/> </one> <?pi 3.14159?>
     <more/> 
    "unbound-prefix-in-entity" [warning]
    如果配置参数“ namespaces ”设置为true并且在实体的替换文本中遇到未绑定的名称空间前缀,则可能引发与实现相关的警告。 由于某些现有解析器可能无法识别实体的替换文本中的未绑定名称空间前缀,因此不会强制执行此警告。
    "unknown-character-denormalization" [fatal]
    如果配置参数“ignore-unknown-character-denormalizations”设置为false并且遇到处理器无法确定规范化属性的字符,则false
    "unsupported-encoding" [fatal]
    如果遇到不受支持的编码,则引发此问题。
    "unsupported-media-type" [fatal]
    如果配置参数“supported-media-types-only”设置为true并且遇到不支持的介质类型,则true

    除了提出已定义的错误和警告之外,预计实现还会针对任何其他错误和警告情况(例如IO错误(未找到文件,权限被拒绝,......),XML格式错误,提出特定于实现的错误和警告)等等。

    另见Document Object Model (DOM) Level 3 Load and Save Specification

    从以下版本开始:
    1.5
    • 字段汇总

      字段  
      变量和类型 字段 描述
      static short ACTION_APPEND_AS_CHILDREN
      将解析操作的结果附加为上下文节点的子项。
      static short ACTION_INSERT_AFTER
      将解析操作的结果作为上下文节点的紧随其后的兄弟插入。
      static short ACTION_INSERT_BEFORE
      将解析操作的结果作为上下文节点的前一个兄弟插入。
      static short ACTION_REPLACE
      将上下文节点替换为解析操作的结果。
      static short ACTION_REPLACE_CHILDREN
      使用解析操作的结果替换上下文节点的所有子节点。
    • 方法摘要

      所有方法  实例方法 抽象方法 
      变量和类型 方法 描述
      void abort()
      中止加载 LSParser当前正在加载的 LSParser
      boolean getAsync()
      true如果 LSParser是异步的, false如果它是同步的。
      boolean getBusy()
      true如果 LSParser当前正忙于加载文档,否则为 false
      DOMConfiguration getDomConfig()
      解析输入源时使用的 DOMConfiguration对象。
      LSParserFilter getFilter()
      当提供过滤器时,实现将在构造DOM树结构时调用过滤器。
      Document parse​(LSInput input)
      从由 LSInput标识的资源中解析XML文档。
      Document parseURI​(String uri)
      从URI引用[ IETF RFC 2396 ]标识的位置解析XML文档。
      Node parseWithContext​(LSInput input, Node contextArg, short action)
      从由 LSInput标识的资源中解析XML片段,并将内容插入到使用 contextaction参数指定的位置的现有文档中。
      void setFilter​(LSParserFilter filter)
      当提供过滤器时,实现将在构造DOM树结构时调用过滤器。
    • 字段详细信息

      • ACTION_APPEND_AS_CHILDREN

        static final short ACTION_APPEND_AS_CHILDREN
        将解析操作的结果附加为上下文节点的子项。 要使此操作起作用,上下文节点必须是ElementDocumentFragment
        另请参见:
        常数字段值
      • ACTION_REPLACE_CHILDREN

        static final short ACTION_REPLACE_CHILDREN
        使用解析操作的结果替换上下文节点的所有子节点。 为了使此动作有效,上下文节点必须是Element ,一个Document ,或DocumentFragment
        另请参见:
        常数字段值
      • ACTION_INSERT_BEFORE

        static final short ACTION_INSERT_BEFORE
        将解析操作的结果作为上下文节点的前一个兄弟插入。 要使此操作起作用,上下文节点的父级必须是ElementDocumentFragment
        另请参见:
        常数字段值
      • ACTION_INSERT_AFTER

        static final short ACTION_INSERT_AFTER
        将解析操作的结果作为上下文节点的紧随其后的兄弟插入。 要使此操作起作用,上下文节点的父级必须是ElementDocumentFragment
        另请参见:
        常数字段值
      • ACTION_REPLACE

        static final short ACTION_REPLACE
        将上下文节点替换为解析操作的结果。 要使此操作起作用,上下文节点必须具有父级,父级必须是ElementDocumentFragment
        另请参见:
        常数字段值
    • 方法详细信息

      • getDomConfig

        DOMConfiguration getDomConfig()
        解析输入源时使用的DOMConfiguration对象。 DOMConfiguration特定于解析操作。 DOMConfiguration对象中的任何参数值都不会自动传递到解析操作创建或使用的DOMConfiguration上的Document对象。 DOM应用程序负责将此DOMConfiguration对象中的任何所需参数值传递给DOMConfiguration对象引用的Document对象。
        除了[ DOM Level 3 Core ]中定义的DOMConfiguration接口中识别的参数外, 5157286513100DOMConfiguration对象LSParser添加或修改以下参数:
        "charset-overrides-xml-encoding"
        true
        [ 可选 ]( 默认 )如果更高级别的协议(如HTTP [ IETF RFC 2616 ])提供正在处理的输入流的字符编码的指示,则将覆盖XML声明或文本声明中指定的任何编码(另请参见第4.3节) .3,“实体中的字符编码”,[ XML 1.0 ])。 LSInput显式设置编码会覆盖协议中的任何编码。
        false
        [ 必需 ]解析器忽略来自更高级别协议的任何字符集编码信息。
        "disallow-doctype"
        true
        [ 可选 ]如果在解析文档时找到doctype节点,则会抛出致命的“doctype-not-allowed”错误。 在处理不允许使用doctype节点的SOAP信封之类的东西时,这很有用。
        false
        [ 必需 ]( 默认 )允许文档中的doctype节点。
        "ignore-unknown-character-denormalizations"
        true
        [ 必需 ]( 默认 )如果在支持[ XML 1.1 ]时验证完全规范化时,处理器遇到无法确定规范化属性的字符,则处理器将忽略由这些字符引起的任何可能的规范化。 [ XML 1.0 ]忽略此参数。
        false
        [ 可选 ]如果遇到处理器无法确定规范化属性的字符,则报告致命的“未知字符非规范化”错误。
        "infoset"
        有关此参数的说明,请参阅DOMConfiguration的定义。 与在[ DOM Level 3 Core ],该参数将默认为trueLSParser
        "namespaces"
        true
        [ 必需 ]( 默认 )执行[ XML Namespaces ]和[ XML Namespaces 1.1 ]中定义的命名空间处理。
        false
        [ 可选 ]不执行命名空间处理。
        "resource-resolver"
        [ 必需 ]对LSResourceResolver对象的引用,或null。 如果遇到外部资源(如外部XML实体或XML模式位置)时,这个参数的值不为空,执行将要求LSResourceResolver在这个参数中引用解决了资源。
        "supported-media-types-only"
        true
        [ 可选 ]检查已解析资源的媒体类型是否为支持的媒体类型。 如果遇到不支持的媒体类型,将引发类型为“unsupported-media-type”的致命错误。 必须始终接受[ IETF RFC 3023 ]中定义的媒体类型。
        false
        [ 必需 ]( 默认 )接受任何媒体类型。
        "validate"
        有关此参数的说明,请参阅DOMConfiguration的定义。 与[ DOM Level 3 Core ]不同,即使此参数设置为false ,也始终完成内部子集的处理。
        "validate-if-schema"
        有关此参数的说明,请参阅DOMConfiguration的定义。 与[ DOM Level 3 Core ]不同,即使此参数设置为false ,也始终完成内部子集的处理。
        "well-formed"
        有关此参数的说明,请参阅DOMConfiguration的定义。 与[ DOM Level 3 Core ]不同,此参数不能设置为false
      • getFilter

        LSParserFilter getFilter()
        当提供过滤器时,实现将在构造DOM树结构时调用过滤器。 过滤器可以选择从正在构造的文档中删除元素,或者提前终止解析。
        在应用了DOMConfiguration参数请求的操作后调用过滤器。 例如,如果“ validate ”设置为true ,则在调用过滤器之前完成验证。
      • setFilter

        void setFilter​(LSParserFilter filter)
        当提供过滤器时,实现将在构造DOM树结构时调用过滤器。 过滤器可以选择从正在构造的文档中删除元素,或者提前终止解析。
        在应用了DOMConfiguration参数请求的操作后调用过滤器。 例如,如果“ validate ”设置为true ,则在调用过滤器之前完成验证。
      • getAsync

        boolean getAsync()
        true如果 LSParser是异步的, false如果它是同步的。
      • getBusy

        boolean getBusy()
        true如果 LSParser当前正忙于加载文档,否则为 false
      • parse

        Document parse​(LSInput input)
                throws DOMException,
                       LSException
        从由 LSInput标识的资源中解析XML文档。
        参数
        input - 要从中读取文档源的 LSInput
        结果
        如果LSParser是同步LSParser ,则返回新创建并填充的Document 如果LSParser是异步的,则返回null ,因为此方法返回时可能尚未构造文档对象。
        异常
        DOMException - INVALID_STATE_ERR:如果 LSParserLSParser.busy属性为 truetrue
        LSException - PARSE_ERR:如果LSParser无法加载XML文档,则引发此问题。 如果DOM应用程序希望获取有关错误的详细信息, DOMErrorHandler使用参数“ error-handler ”附加DOMErrorHandler
      • parseURI

        Document parseURI​(String uri)
                   throws DOMException,
                          LSException
        从URI引用[ IETF RFC 2396 ]标识的位置解析XML文档。 如果URI包含片段标识符(请参阅[ IETF RFC 2396 ]中的第4.1节),则此规范未定义该行为,此规范的未来版本可能会定义该行为。
        参数
        uri - 要读取的XML文档的位置。
        结果
        如果LSParser是同步LSParser ,则返回新创建并填充的Document ,如果发生错误,则返回null 如果LSParser是异步的,则返回null ,因为此方法返回时可能尚未构造文档对象。
        异常
        DOMException - INVALID_STATE_ERR:如果 LSParser.busy属性为 truetrue
        LSException - PARSE_ERR:如果LSParser无法加载XML文档,则引发此问题。 如果DOM应用程序希望获取有关错误的详细信息, DOMErrorHandler使用参数“ error-handler ”附加DOMErrorHandler
      • parseWithContext

        Node parseWithContext​(LSInput input,
                              Node contextArg,
                              short action)
                       throws DOMException,
                              LSException
        从由LSInput标识的资源中解析XML片段,并将内容插入到使用contextaction参数指定的位置的现有文档中。 解析输入流时,上下文节点(或其父节点,取决于将插入结果的位置)用于解析未绑定的名称空间前缀。 上下文节点的ownerDocument节点(或节点本身,如果类型为DOCUMENT_NODE的节点)用于解析默认属性和实体引用。
        当新数据插入到文档中时,每个新的直接子节点或上下文节点的兄弟节点都会触发至少一个突变事件。
        如果上下文节点是Document节点和行动是ACTION_REPLACE_CHILDREN ,然后就是作为上下文节点传递的文档将被改变,以使得其xmlEncodingdocumentURIxmlVersioninputEncodingxmlStandalone ,和所有其他的此类属性都设置为它们如果使用LSParser.parse()解析输入源,则将设置为。
        即使LSParser是异步的( LSParser.asynctrue ),此方法始终是同步的。
        如果在分析中发生错误,呼叫者通过通知ErrorHandler带有“相关实例error-handler所述的”参数DOMConfiguration
        调用parseWithContext ,将忽略以下配置参数的值,并始终使用其默认值:“ validate ”,“ validate-if-schema ”和“ element-content-whitespace ”。 其他参数将被正常处理,并且解析器应该调用LSParserFilter就像解析整个文档一样。
        参数
        input - 要从中读取源文档的LSInput 源文档必须是XML片段,即除完整XML文档之外的任何内容(类型为DOCUMENT_NODE的上下文节点,操作为ACTION_REPLACE_CHILDREN ),DOCTYPE(内部子集),实体声明,符号声明,或XML或文本声明。
        contextArg - 用作正在分析的数据的上下文的节点。 此节点必须是Document节点, DocumentFragment节点或允许作为Element节点的子节点的类型的节点,例如,它不能是Attribute节点。
        action - 此参数描述在要插入的新节点集和上下文节点的现有子节点之间应采取的操作。 可能的动作集在上面的ACTION_TYPES定义。
        结果
        返回作为解析操作结果的节点。 如果结果是多个顶级节点,则返回第一个节点。
        异常
        DOMException - HIERARCHY_REQUEST_ERR:如果内容无法替换,则在上下文节点之前,之后或作为子节点Node.insertBefore Node.replaceChild (参见[ DOM Level 3 Core ]中的Node.insertBeforeNode.replaceChild )。
        NOT_SUPPORTED_ERR:如果LSParser不支持此方法,或者上下文节点的类型为Document且DOM实现不支持替换DocumentType子级或Element子级,则DocumentType Element
        NO_MODIFICATION_ALLOWED_ERR:如果上下文节点是只读节点并且内容被附加到其子列表,或者上下文节点的父节点是只读节点并且内容正在其子列表中插入,则引发此异常。
        INVALID_STATE_ERR:如果LSParser.busy属性为truetrue
        LSException - PARSE_ERR:如果LSParser无法加载XML片段,则引发此问题。 如果DOM应用程序希望获取有关错误的详细信息, DOMErrorHandler使用参数“ error-handler ”附加DOMErrorHandler
      • abort

        void abort()
        Abort the loading of the document that is currently being loaded by the LSParser. If the LSParser is currently not busy, a call to this method does nothing.