compact2, compact3

org.w3c.dom.ls

Interface LSParser

public interface LSParser

一个接口的对象，可以建立，或增强，从各种输入源的DOM树。

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

在[ DOM Level 3 Core ]的规定，当一个文件是第一个提供了通过LSParser：

• 永远不会有node_text型两相邻节点，永远不会有空文本节点。
• 预计value和nodeValue属性的Attr节点开始返回XML 1.0 normalized value。然而，如果参数“ validate-if-schema”和“ datatype-normalization”设置为true，取决于所用的属性归一化，属性值可能不同于XML 1属性归一化得到的。如果参数“ datatype-normalization”设置为false，XML 1属性的规范化是保证发生，如果属性列表不包含命名空间声明，对Element节点attributes属性代表XML Information Set ] [定义属性[属性]。

异步LSParser对象预计也实现events::EventTarget界面，事件监听器可以异步LSParser注册的对象。

通过异步LSParser对象支持的事件：

负载

的 LSParser完成加载文件。又见的 LSLoadEvent接口的定义。

进步

LSParser进展的信号数据解析。此规范不试图定义在要发送的进程事件时的确切情况。这是故意留下作为执行依赖。这里有一个应用程序如何调度进度事件的示例：一旦解析器开始接收数据，则发送一个进度事件以指示解析启动。从那里，一个进度事件被发送每4096个字节的数据，接收和处理。这只是一个例子，但是，实现可以选择在解析过程中随时调度进度事件，或者根本不进行调度。又见的 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]

提出如果配置参数“允许文档类型”设置为 true和DOCTYPE遇到。

"no-input-specified" [fatal]

当加载一个文件没有输入在 LSInput对象指定。

"pi-base-uri-not-preserved" [warning]

提出如果遇到一个处理指令在一个位置的处理指令的基URI不能保存。一个例子，这个警告将是如果配置参数” entities”设置为 false和下面的XML文件解析：

<！DOCTYPE根[ <！实体系统的子目录/ myentity。耳鼻喉] >
 
  
   
          
          
          
        
          
        <根>
         
           
         
           
           
           
    
   
  和E；< /根>
 
  
   
          
          
          
        
          
        

和 subdir/myentity.ent包含：

 
  
   
          
          
          
        
          
        <一> 
  
   
    
           
           
           
         
           
         <两个 个>
           >？PI 3.14159？> 
          <更多> 
         
 
  
   
          
          
          
        
          
        

"unbound-prefix-in-entity" [warning]

实施相关的警告，可如果配置参数” namespaces”设置为 true和未绑定命名空间前缀是一个实体的替换文本中遇到了。这个警告不是强制执行以来提高一些现有的解析器可能不认识在实体替换文本绑定命名空间前缀。

"unknown-character-denormalization" [fatal]

提出如果配置参数“忽略未知字符denormalizations”设置为 false和字符时，处理器无法确定归一化特性。

"unsupported-encoding" [fatal]

提出如果遇到不支持的编码。

"unsupported-media-type" [fatal]

提出如果配置参数支持的媒体类型”设置为 true遇到不支持的媒体类型。

除了提高定义错误和警告，实现将提高对任何其他错误和警告的情况下如IO错误实施的具体错误和警告（未找到文件，没有权限，…），XML的格式错误，等等。

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

Field Summary

Fields

Modifier and Type	Field and Description
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 用解析操作的结果替换上下文节点的所有子节点。

方法摘要

Modifier and Type	Method and Description
void	abort() 有关文件，目前正在由 LSParser加载的加载。
boolean	getAsync() true如果 LSParser是异步的， false如果是同步的。
boolean	getBusy() true如果 LSParser目前正在忙于加载文件，否则 false。
DOMConfiguration	getDomConfig() 的 DOMConfiguration对象用于分析输入源。
LSParserFilter	getFilter() 当一个过滤器设置，实现将呼唤过滤器是构造DOM树结构。
Document	parse(LSInput input) 解析一个XML文件从资源的 LSInput鉴定。
Document	parseURI(String uri) 解析一个XML文件从一个位置的URI引用[ IETF RFC 2396 ]确定。
Node	parseWithContext(LSInput input, Node contextArg, short action) 解析从资源的 LSInput确定一个XML片段，插入到现有的文档内容在指定位置与 context和 action参数。
void	setFilter(LSParserFilter filter) 当一个过滤器设置，实现将呼唤过滤器是构造DOM树结构。

Field Detail

ACTION_APPEND_AS_CHILDREN

static final short ACTION_APPEND_AS_CHILDREN

附加分析操作的结果作为上下文节点的子节点。这一行动工作，上下文节点必须是一个 Element或 DocumentFragment。

另请参见：

Constant Field Values

ACTION_REPLACE_CHILDREN

static final short ACTION_REPLACE_CHILDREN

用解析操作的结果替换上下文节点的所有子节点。这一行动工作，上下文节点必须是一个 Element，一 Document，或 DocumentFragment。

另请参见：

Constant Field Values

ACTION_INSERT_BEFORE

static final short ACTION_INSERT_BEFORE

将解析操作的结果插入上下文节点的立即前面的兄弟姐妹。这一行动的工作上下文节点的父节点必须是一个 Element或 DocumentFragment。

另请参见：

Constant Field Values

ACTION_INSERT_AFTER

static final short ACTION_INSERT_AFTER

将解析操作的结果插入上下文节点的紧随其后的兄弟姐妹。这一行动的工作上下文节点的父节点必须是一个 Element或 DocumentFragment。

另请参见：

Constant Field Values

ACTION_REPLACE

static final short ACTION_REPLACE

用解析操作的结果替换上下文节点。这一行动工作，上下文节点必须有一个父，与母必须是一个 Element或 DocumentFragment。

另请参见：

Constant Field Values

方法详细信息

getDomConfig

DOMConfiguration getDomConfig()

的 DOMConfiguration对象用于分析输入源。这 DOMConfiguration具体分析操作。从这个 DOMConfiguration对象的任何参数值是通过自动对 Document，创建的 DOMConfiguration对象或使用，通过分析操作。DOM应用程序负责传递所需的参数值，从这个 DOMConfiguration对象的 DOMConfiguration Document对象引用的对象。除了参数确认对[ DOM Level 3 Core ]定义的 DOMConfiguration接口
，为 LSParser的 DOMConfiguration对象添加或修改下列参数：

"charset-overrides-xml-encoding"

true

[可选]（默认）如果更高级别的协议如HTTP [ IETF RFC 2616 ]提供的输入流被处理的字符编码的指示，这将覆盖任何编码的XML声明中或文本中指定的声明（参见第4.3.3，”实体中的字符编码”，在[ XML 1.0 ]）。显式设置编码在 LSInput重写任何编码的协议。

false

[要求]解析器忽略任何来自更高级别协议的字符集的编码信息。

"disallow-doctype"

true

[可选]抛出一个致命的错误 “不允许DOCTYPE”如果DOCTYPE节点解析文档时发现。这是有用的在处理诸如SOAP信封里的DOCTYPE节点不允许。

false

[要求]（默认）允许在文档的DOCTYPE节点。

"ignore-unknown-character-denormalizations"

true

[要求]（默认）如果，而验证的完全正常化时 XML 1.1 ] [支持处理器遇到的字符，它不能确定的规范性质，那么处理器将忽略任何可能造成denormalizations这些字符。为 XML 1.0 ] [此参数被忽略。

false

[可选]报告一个致命错误如果 “未知字符化”字符时，处理器无法确定归一化特性。

"infoset"

看到这样的描述 DOMConfiguration参数定义。不同于[ DOM Level 3 Core ]，此参数将默认为 LSParser true。

"namespaces"

true

[要求]（默认）执行处理命名空间为[ ]和[ ] XML Namespaces XML Namespaces 1.1定义。

false

[可选]不执行命名空间处理。

"resource-resolver"

[要求]参考一 LSResourceResolver对象，或空。如果该参数的值不为空时，外部资源（如外部XML实体或一个XML Schema的位置）时，执行将要求该参数引用的 LSResourceResolver解决资源。

"supported-media-types-only"

true

[可选]检查已解析的资源的媒体类型是支持的媒体类型。如果遇到一个不支持的媒体类型，类型 “不支持的媒体类型”致命错误将提高。媒体类型定义在[ 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

解析一个XML文件从资源的 LSInput鉴定。

参数

input - LSInput从文档的来源是读。

结果

如果 LSParser是同步 LSParser，新创建的和密集的 Document返回。如果 LSParser是异步的， null从文档对象可能尚未建成时，此方法返回返回。

异常

DOMException - invalid_state_err：如果 LSParser的 LSParser.busy属性 true提出。

LSException - parse_err：如果 LSParser无法加载XML文件了。DOM应用程序应该附上一 DOMErrorHandler使用参数“ error-handler“如果他们希望得到的错误信息。

parseURI

Document parseURI(String uri)
           throws DOMException,
                  LSException

解析一个XML文件从一个位置的URI引用[ IETF RFC 2396 ]确定。如果URI包含一个片段标识符（见第4.1节在[ IETF RFC 2396 ]），行为不在本规范中定义的，这个规范的未来版本可能定义行为。

参数

uri - XML文档被阅读的位置。

结果

如果 LSParser是同步 LSParser，新创建的和密集的 Document返回，或 null如果发生错误。如果 LSParser是异步的， null从文档对象可能尚未建成时，此方法返回返回。

异常

DOMException - invalid_state_err：提出如果 LSParser.busy属性 true。

LSException - parse_err：如果 LSParser无法加载XML文件了。DOM应用程序应该附上一 DOMErrorHandler使用参数“ error-handler“如果他们希望得到的错误信息。

parseWithContext

Node parseWithContext(LSInput input,
                      Node contextArg,
                      short action)
               throws DOMException,
                      LSException

解析从资源的 LSInput确定一个XML片段，插入到现有的文档内容在指定位置与 context和 action参数。当解析输入流，上下文节点（或其母公司，根据结果将被插入）是用来解决绑定命名空间前缀。上下文节点的 ownerDocument节点（或节点本身如果型 DOCUMENT_NODE节点）是用来解决默认属性和实体引用。
作为新的数据插入到文档中，至少一个突变事件触发每新的直接子或兄弟姐妹的上下文节点。
如果上下文节点是一个 Document节点和行动是 ACTION_REPLACE_CHILDREN，然后文件是作为上下文节点通过将改变这样的 xmlEncoding， documentURI， xmlVersion， inputEncoding， xmlStandalone，和所有其他属性都设置为他们将设置当输入源解析使用 LSParser.parse()。
这个方法始终是同步的，即使 LSParser是异步的（ LSParser.async是 true）。
如果在分析出现错误，打电话通知通过 ErrorHandler实例相关联的“ error-handler”的 DOMConfiguration参数。
parseWithContext呼叫时，下列配置参数将被忽略，其默认值是相反的价值观：“ validate”、“ validate-if-schema”、和“ element-content-whitespace”。其他参数将被视为正常，和分析器预计称 LSParserFilter就像整个文档被解析。

参数

input - LSInput从源文件被读取。源文件必须是一个XML片段，即除了一个完整的XML文档（除非类型 DOCUMENT_NODE，上下文节点和动作 ACTION_REPLACE_CHILDREN），一个DOCTYPE（内部子集），实体声明（S），符号声明（S），或XML或文本声明（S）。

contextArg的节点作为被解释的上下文的数据。该节点必须是一 Document节点，一个 DocumentFragment节点或节点的类型可以作为一个 Element节点的子节点，它不能成为一个 Attribute节点。

action -这个参数描述应该采取的动作节点插入新的设置和上下文节点之间存在的孩子。可能的动作集是定义在 ACTION_TYPES以上。

结果

返回解析操作的结果的节点。如果结果是多个顶级节点，则返回第一个节点。

异常

DOMException - hierarchy_request_err：如果内容不能代替了，被插入前，后，或作为一个上下文节点的孩子（见[ DOM Level 3 Core ]也 Node.insertBefore或 Node.replaceChild）。
not_supported_err：如果 LSParser不支持此方法提高了，或者如果上下文节点的类型是 Document和DOM实现不支持更换的 DocumentType Element孩子或孩子。
no_modification_allowed_err：如果上下文节点是一个只读节点和内容提出追加到其子列表，或者如果上下文节点的父节点是只读节点和内容被插入在其子列表。
invalid_state_err：如果 LSParser.busy属性 true提出。

LSException - parse_err：如果 LSParser无法加载XML片段了。DOM应用程序应该附上一 DOMErrorHandler使用参数“ error-handler“如果他们希望得到的错误信息。

abort

void abort()

有关文件，目前正在由 LSParser加载的加载。如果 LSParser目前不忙，调用这个方法不会。