Most visited

Recently visited

Results for

Added in API level 8

LSParser

public interface LSParser

org.w3c.dom.ls.LSParser

一个对象的接口，能够从各种输入源构建或扩充DOM树。

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

如[ DOM Level 3 Core ]中所述，当首次通过LSParser使文档可用时：

预计异步 LSParser对象还将实现 events::EventTarget接口，以便可以在异步 LSParser对象上注册事件侦听器。

由异步 LSParser对象支持的事件是：

load
The LSParser finishes to load the document. See also the definition of the LSLoadEvent interface.
progress
The LSParser signals progress as data is parsed. This specification does not attempt to define exactly when progress events should be dispatched. That is intentionally left as implementation-dependent. Here is one example of how an application might dispatch progress events: Once the parser starts receiving data, a progress event is dispatched to indicate that the parsing starts. From there on, a progress event is dispatched for every 4096 bytes of data that is received and processed. This is only one example, though, and implementations can choose to dispatch progress events at any time while parsing, or not dispatch them at all. See also the definition of the LSProgressEvent interface.

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

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

"check-character-normalization-failure" [error]
Raised if the parameter " check-character-normalization" is set to true and a string is encountered that fails normalization checking.
"doctype-not-allowed" [fatal]
Raised if the configuration parameter "disallow-doctype" is set to true and a doctype is encountered.
"no-input-specified" [fatal]
Raised when loading a document and no input is specified in the LSInput object.
"pi-base-uri-not-preserved" [warning]
Raised if a processing instruction is encountered in a location where the base URI of the processing instruction can not be preserved. One example of a case where this warning will be raised is if the configuration parameter " entities" is set to false and the following XML file is parsed: 
 <!DOCTYPE root [ <!ENTITY e SYSTEM 'subdir/myentity.ent' ]>
 <root> &e; </root>
And subdir/myentity.ent contains: 
<one> <two/> </one> <?pi 3.14159?>
 <more/>
"unbound-prefix-in-entity" [warning]
An implementation dependent warning that may be raised if the configuration parameter " namespaces" is set to true and an unbound namespace prefix is encountered in an entity's replacement text. Raising this warning is not enforced since some existing parsers may not recognize unbound namespace prefixes in the replacement text of entities.
"unknown-character-denormalization" [fatal]
Raised if the configuration parameter "ignore-unknown-character-denormalizations" is set to false and a character is encountered for which the processor cannot determine the normalization properties.
"unsupported-encoding" [fatal]
Raised if an unsupported encoding is encountered.
"unsupported-media-type" [fatal]
Raised if the configuration parameter "supported-media-types-only" is set to true and an unsupported media type is encountered.

除了提出定义的错误和警告之外，实现还应该针对任何其他错误和警告情况（例如IO错误（文件未找到，权限被拒绝，...），XML格式错误等）引发实现特定的错误和警告。等等。

另请参阅 Document Object Model (DOM) Level 3 Load and Save Specification 。

Summary

Constants
short ACTION_APPEND_AS_CHILDREN

将解析操作的结果追加为上下文节点的子节点。
short ACTION_INSERT_AFTER

将解析操作的结果作为上下文节点的紧随其后的兄弟节点。
short ACTION_INSERT_BEFORE

将解析操作的结果作为上下文节点的前一个兄弟节点。
short ACTION_REPLACE

将上下文节点替换为解析操作的结果。
short ACTION_REPLACE_CHILDREN

将上下文节点的所有子节点替换为解析操作的结果。

Public methods
abstract void abort()

中止加载 LSParser当前正在加载的 LSParser 。
abstract boolean getAsync()

true如果 LSParser是异步的， false是同步的。
abstract boolean getBusy()

true如果 LSParser当前正忙于加载文档，否则为 false 。
abstract DOMConfiguration getDomConfig()

解析输入源时使用的 DOMConfiguration对象。
abstract LSParserFilter getFilter()

当提供过滤器时，实现会在构建DOM树结构时调用过滤器。
abstract Document parse(LSInput input)

解析来自 LSInput标识的资源的XML文档。
abstract Document parseURI(String uri)

从URI参考标识的位置解析XML文档[ IETF RFC 2396 ]。
abstract Node parseWithContext(LSInput input, Node contextArg, short action)

从 LSInput标识的资源中解析XML片段，并将该内容插入到使用 context和 action参数指定的位置的现有文档中。
abstract void setFilter(LSParserFilter filter)

当提供过滤器时，实现会在构建DOM树结构时调用过滤器。

Constants

ACTION_APPEND_AS_CHILDREN

Added in API level 8 
short ACTION_APPEND_AS_CHILDREN

将解析操作的结果追加为上下文节点的子节点。 要使此操作起作用，上下文节点必须是Element或DocumentFragment 。

常数值：1（0x00000001）

ACTION_INSERT_AFTER

Added in API level 8 
short ACTION_INSERT_AFTER

将解析操作的结果作为上下文节点的紧随其后的兄弟节点。 要执行此操作，上下文节点的父级必须是Element或DocumentFragment 。

常量值：4（0x00000004）

ACTION_INSERT_BEFORE

Added in API level 8 
short ACTION_INSERT_BEFORE

将解析操作的结果作为上下文节点的前一个兄弟节点。 要使此操作工作，上下文节点的父级必须是Element或DocumentFragment 。

常量值：3（0x00000003）

ACTION_REPLACE

Added in API level 8 
short ACTION_REPLACE

将上下文节点替换为解析操作的结果。 要使此操作起作用，上下文节点必须具有父级，并且父级必须是Element或DocumentFragment 。

常量值：5（0x00000005）

ACTION_REPLACE_CHILDREN

Added in API level 8 
short ACTION_REPLACE_CHILDREN

将上下文节点的所有子节点替换为解析操作的结果。 为了使此动作有效，上下文节点必须是Element ，一个Document或者DocumentFragment 。

常量值：2（0x00000002）

Public methods

abort

Added in API level 8 
void abort ()

中止加载当前由LSParser加载的LSParser 。 如果LSParser当前不忙，则对此方法的调用不起作用。

getAsync

Added in API level 8 
boolean getAsync ()

true如果 LSParser是异步的， false是同步的。

Returns
boolean

getBusy

Added in API level 8 
boolean getBusy ()

true如果 LSParser当前正忙于加载文档，否则为 false 。

Returns
boolean

getDomConfig

Added in API level 8 
DOMConfiguration getDomConfig ()

解析输入源时使用的DOMConfiguration对象。 这DOMConfiguration是特定于解析操作。 从这个无参数值DOMConfiguration对象被自动传递到DOMConfiguration对象上的Document时创建，或所使用的，由所述解析操作。 DOM应用程序负责DOMConfiguration对象的任何所需参数值传递给由DOMConfiguration对象引用的Document对象。
除了[ DOM Level 3 Core ]中定义的DOMConfiguration接口中识别的参数之外， LSParser的DOMConfiguration对象LSParser添加或修改了以下参数：

"charset-overrides-xml-encoding"
true
[ optional] ( default) If a higher level protocol such as HTTP [ IETF RFC 2616] provides an indication of the character encoding of the input stream being processed, that will override any encoding specified in the XML declaration or the Text declaration (see also section 4.3.3, "Character Encoding in Entities", in [ XML 1.0]). Explicitly setting an encoding in the LSInput overrides any encoding from the protocol.
false
[ required] The parser ignores any character set encoding information from higher-level protocols.
"disallow-doctype"
true
[ optional] Throw a fatal "doctype-not-allowed" error if a doctype node is found while parsing the document. This is useful when dealing with things like SOAP envelopes where doctype nodes are not allowed.
false
[ required] ( default) Allow doctype nodes in the document.
"ignore-unknown-character-denormalizations"
true
[ required] ( default) If, while verifying full normalization when [ XML 1.1] is supported, a processor encounters characters for which it cannot determine the normalization properties, then the processor will ignore any possible denormalizations caused by these characters. This parameter is ignored for [ XML 1.0].
false
[ optional] Report an fatal "unknown-character-denormalization" error if a character is encountered for which the processor cannot determine the normalization properties.
"infoset"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [ DOM Level 3 Core] , this parameter will default to true for LSParser.
"namespaces"
true
[ required] ( default) Perform the namespace processing as defined in [ XML Namespaces] and [ XML Namespaces 1.1] .
false
[ optional] Do not perform the namespace processing.
"resource-resolver"
[ required] A reference to a LSResourceResolver object, or null. If the value of this parameter is not null when an external resource (such as an external XML entity or an XML schema location) is encountered, the implementation will request that the LSResourceResolver referenced in this parameter resolves the resource.
"supported-media-types-only"
true
[ optional] Check that the media type of the parsed resource is a supported media type. If an unsupported media type is encountered, a fatal error of type "unsupported-media-type" will be raised. The media types defined in [ IETF RFC 3023] must always be accepted.
false
[ required] ( default) Accept any media type.
"validate"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [ DOM Level 3 Core] , the processing of the internal subset is always accomplished, even if this parameter is set to false.
"validate-if-schema"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [ DOM Level 3 Core] , the processing of the internal subset is always accomplished, even if this parameter is set to false.
"well-formed"
See the definition of DOMConfiguration for a description of this parameter. Unlike in [ DOM Level 3 Core] , this parameter cannot be set to false.

Returns
DOMConfiguration

getFilter

Added in API level 8 
LSParserFilter getFilter ()

当提供过滤器时，实现会在构建DOM树结构时调用过滤器。 过滤器可以选择从正在构建的文档中移除元素，或者提前终止解析。
在应用了DOMConfiguration参数所要求的操作之后，将调用该过滤器。 例如，如果“ validate ”设置为true ，则在调用过滤器之前完成验证。

Returns
LSParserFilter

parse

Added in API level 8 
Document parse (LSInput input)

从 LSInput标识的资源中解析XML文档。

Parameters
input LSInput: The LSInput from which the source of the document is to be read.
Returns
Document If the LSParser is a synchronous LSParser, the newly created and populated Document is returned. If the LSParser is asynchronous, null is returned since the document object may not yet be constructed when this method returns.
Throws
DOMException INVALID_STATE_ERR: Raised if the LSParser's LSParser.busy attribute is true.
LSException PARSE_ERR: Raised if the LSParser was unable to load the XML document. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

parseURI

Added in API level 8 
Document parseURI (String uri)

从URI参考标识的位置解析XML文档[ IETF RFC 2396 ]。 如果URI包含片段标识符（参见[ IETF RFC 2396 ]中的第4.1节），则该行为不是由本规范定义的，本规范的未来版本可能会定义行为。

Parameters
uri String: The location of the XML document to be read.
Returns
Document If the LSParser is a synchronous LSParser, the newly created and populated Document is returned, or null if an error occured. If the LSParser is asynchronous, null is returned since the document object may not yet be constructed when this method returns.
Throws
DOMException INVALID_STATE_ERR: Raised if the LSParser.busy attribute is true.
LSException PARSE_ERR: Raised if the LSParser was unable to load the XML document. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

parseWithContext

Added in API level 8 
Node parseWithContext (LSInput input, 
                Node contextArg, 
                short action)

从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就像整个文档被解析一样。

Parameters
input LSInput: The LSInput from which the source document is to be read. The source document must be an XML fragment, i.e. anything except a complete XML document (except in the case where the context node of type DOCUMENT_NODE, and the action is ACTION_REPLACE_CHILDREN), a DOCTYPE (internal subset), entity declaration(s), notation declaration(s), or XML or text declaration(s).
contextArg Node: The node that is used as the context for the data that is being parsed. This node must be a Document node, a DocumentFragment node, or a node of a type that is allowed as a child of an Element node, e.g. it cannot be an Attribute node.
action short: This parameter describes which action should be taken between the new set of nodes being inserted and the existing children of the context node. The set of possible actions is defined in ACTION_TYPES above.
Returns
Node Return the node that is the result of the parse operation. If the result is more than one top-level node, the first one is returned.
Throws
DOMException HIERARCHY_REQUEST_ERR: Raised if the content cannot replace, be inserted before, after, or as a child of the context node (see also Node.insertBefore or Node.replaceChild in [DOM Level 3 Core] ).
NOT_SUPPORTED_ERR: Raised if the LSParser doesn't support this method, or if the context node is of type Document and the DOM implementation doesn't support the replacement of the DocumentType child or Element child.
NO_MODIFICATION_ALLOWED_ERR: Raised if the context node is a read only node and the content is being appended to its child list, or if the parent node of the context node is read only node and the content is being inserted in its child list.
INVALID_STATE_ERR: Raised if the LSParser.busy attribute is true.
LSException PARSE_ERR: Raised if the LSParser was unable to load the XML fragment. DOM applications should attach a DOMErrorHandler using the parameter " error-handler" if they wish to get details on the error.

setFilter

Added in API level 8 
void setFilter (LSParserFilter filter)

当提供过滤器时，实现会在构建DOM树结构时调用过滤器。 过滤器可以选择从正在构建的文档中移除元素，或者提前终止解析。
在应用了DOMConfiguration参数所要求的操作后，将调用该过滤器。 例如，如果“ validate ”设置为true ，则在调用过滤器之前完成验证。

Parameters
filter LSParserFilter
Android开发手册

Hooray!