|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
public interface LSParser
可以构建的对象接口，或者参数、来自各种输入源的 DOM 树。
LSParser 提供了用于解析 XML 和构建相应的 DOM 文档结构的 API。LSParser 实例可以通过调用 DOMImplementationLS.createLSParser() 方法获取。
如 [DOM Level 3 Core] 中指定的那样，当通过 LSParser 第一次使文档可供使用时：
Attr 节点的 value 和 nodeValue 属性最初返回《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 通知进度情况。此规范并不尝试精确定义应该何时调度进度事件。而是有意让其具有实现依赖性。下面是一个应用程序如何调度进度事件的示例：一旦解析器开始接收数据，则将调度进度事件，以表示解析已开始。从这时起，为接收和处理的每 4096 个字节数据调度进度事件。但这只是一个示例，实现可以在解析期间的任何时间选择调度进度事件，或者根本不调度这些事件。另请参见 LSProgressEvent 接口的定义。注：此规范中定义的所有事件都使用名称空间 URI "http://www.w3.org/2002/DOMLS"。
在解析输入源时，通过错误处理程序（LSParser.domConfig 的 "error-handler" 参数）将错误报告给应用程序。此规范决不尝试定义解析 XML 或者其他任何标记时所有可能发生的错误，但对一些常见的错误情形做了定义。此规范定义的错误和警告类型 (DOMError.type) 包括：
"check-character-normalization-failure" [error] "doctype-not-allowed" [fatal]true 并且遇到了 doctype，则将引发此错误。 "no-input-specified" [fatal]LSInput 对象中指定输入时引发此错误。 "pi-base-uri-not-preserved" [warning]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]true 并且在实体的替换文本中碰到了未绑定的名称空间前缀时,可以引发此警告。并非强制引发此警告，因为有些现有的解析器不能在实体的替换文本中识别未绑定的名称空间前缀。 "unknown-character-denormalization" [fatal]false 并且遇到了处理器无法为其确定标准化属性的字符，则引发此错误。 "unsupported-encoding" [fatal]"unsupported-media-type" [fatal]true 并且遇到了不支持的媒体类型，则引发此错误。 除了引发定义的错误和警告之外，期望实现应该对其他任何错误和警告情况，例如 IO 错误（未找到文件，权限被拒绝）、XML 格式良好性错误等引发特定于实现的错误和警告。
另请参见《Document Object Model (DOM) Level 3 Load and Save Specification》。
| 字段摘要 | |
|---|---|
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 加载的文档的加载。 |
boolean |
getAsync()
如果 LSParser 是异步的，为 true，如果它是同步的，则为 false。 |
boolean |
getBusy()
如果 LSParser 当前正忙于加载文档，则为 true，否则为 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 片段，并将其内容插入到用 context 和 action 参数指定的位置的现有文档。 |
void |
setFilter(LSParserFilter filter)
当提供过滤器时，实现将在构建 DOM 树结构时调出该过滤器。 |
| 字段详细信息 |
|---|
static final short ACTION_APPEND_AS_CHILDREN
Element 或 DocumentFragment。
static final short ACTION_REPLACE_CHILDREN
Element、Document 或 DocumentFragment。
static final short ACTION_INSERT_BEFORE
Element 或 DocumentFragment。
static final short ACTION_INSERT_AFTER
Element 或 DocumentFragment。
static final short ACTION_REPLACE
Element 或 DocumentFragment。
| 方法详细信息 |
|---|
DOMConfiguration getDomConfig()
DOMConfiguration 对象。此 DOMConfiguration 特定于解析操作。在由解析操作创建或使用的 Document 上，没有参数值从此 DOMConfiguration 对象被自动传递到 DOMConfiguration 对象。DOM 应用程序负责将任何所需的参数值从此 DOMConfiguration 对象传递到由 Document 对象引用的 DOMConfiguration 对象。LSParser 的 DOMConfiguration 对象还可以添加或修改以下参数：
"charset-overrides-xml-encoding"trueLSInput 中设置编码将重写协议中的任何编码。false"disallow-doctype"truefalse"ignore-unknown-character-denormalizations"truefalse"infoset"DOMConfiguration 的定义。与在 [DOM Level 3 Core] 中不同，对于 LSParser，此参数将默认为 true。 "namespaces"truefalse"resource-resolver"LSResourceResolver 对象的引用，或为 null。如果遇到外部资源（如外部 XML 实体或 XML 模式位置）时此参数的值不为 null，则实现将请求在此参数中引用的 LSResourceResolver 解析该资源。 "supported-media-types-only"truefalse"validate"DOMConfiguration 的定义。与在 [DOM Level 3 Core] 中不同，总是要完成对内部子集的处理，即使此参数设置为 false。 "validate-if-schema"DOMConfiguration 的定义。与在 [DOM Level 3 Core] 中不同，总是要完成对内部子集的处理，即使此参数设置为 false。"well-formed"DOMConfiguration 的定义。与在 [DOM Level 3 Core] 中不同，不能将此参数设置为 false。
LSParserFilter getFilter()
DOMConfiguration 参数请求的操作后调用。例如，如果 "validate" 设置为 true，则在调用过滤器前进行验证。
void setFilter(LSParserFilter filter)
DOMConfiguration 参数请求的操作后调用。例如，如果 "validate" 设置为 true，则在调用过滤器前进行验证。
boolean getAsync()
LSParser 是异步的，为 true，如果它是同步的，则为 false。
boolean getBusy()
LSParser 当前正忙于加载文档，则为 true，否则为 false。
Document parse(LSInput input)
throws DOMException,
LSException
LSInput 标识的资源中解析 XML 文档。
input - 从其中读取文档的源的 LSInput。
LSParser 是同步 LSParser，则将返回新创建并填充的 Document。如果 LSParser 是异步的，则返回 null，因为当此方法返回时，还不能构建该文档对象。
DOMException - INVALID_STATE_ERR:如果 LSParser 的 LSParser.busy 属性为 true，则引发此异常。
LSException - PARSE_ERR:如果 LSParser 无法加载 XML 文档，则引发此异常。如果 DOM 应用程序想获得关于错误的详细信息，则它必须附加一个使用参数 "error-handler" 的 DOMErrorHandler。
Document parseURI(String uri)
throws DOMException,
LSException
uri - 将读取的 XML 文档的位置。
LSParser 是同步 LSParser，则将返回新创建并已填充的 Document，如果发生错误，则返回 null。如果 LSParser 是异步的，则返回 null，因为当此方法返回时，还不可以构建该文档对象。
DOMException - INVALID_STATE_ERR:如果 LSParser.busy 属性为 true，则将引发此异常。
LSException - PARSE_ERR:如果 LSParser 无法加载 XML 文档，则将引发此异常。如果 DOM 应用程序想获得关于错误的详细信息，则它必须附加一个使用参数 "error-handler" 的 DOMErrorHandler。
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）也是如此。DOMConfiguration 的 "error-handler" 参数相关联的 ErrorHandler 实例通知调用者。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:如果内容不能替换、插入到上下文节点的前面、后面或作为它的子节点（另请参见 [DOM Level 3 Core] 中的 Node.insertBefore 或 Node.replaceChild），则引发此异常。 LSParser 不支持此方法，或者上下文节点是类型 Document，并且 DOM 实现不支持替换 DocumentType 子节点或 Element 子节点，则引发此异常。 LSParser.busy 属性为 true，则将引发此异常。
LSException - PARSE_ERR:如果 LSParser 无法加载 XML 片段，则将引发此异常。如果 DOM 应用程序想获得关于错误的详细信息，则它必须附加一个使用参数 "error-handler" 的 DOMErrorHandler。void abort()
LSParser 加载的文档的加载。如果当前 LSParser 不忙，则调用此方法无效。
|
JavaTM 2 Platform Standard Ed. 6 |
|||||||||
| 上一个类 下一个类 | 框架 无框架 | |||||||||
| 摘要： 嵌套 | 字段 | 构造方法 | 方法 | 详细信息： 字段 | 构造方法 | 方法 | |||||||||
版权所有 2008 Sun Microsystems, Inc. 保留所有权利。请遵守GNU General Public License, version 2 only。