org.w3c.dom.ls
接口 LSParserFilter

public interface LSParserFilter

LSParserFilter 为应用程序提供了在解析期间构建节点时检查这些节点的能力。由于要检查每个节点，所以可能会修改或删除这些节点，或者会提前终止整个解析。

此时解析器会调用任何过滤器器方法，所有者 Document 和 DOMImplementation 对象存在并可访问。从不会将文档元素传递给 LSParserFilter 方法，即不可能过滤出文档元素。Document、DocumentType、Notation、Entity 和 Attr 节点从不会被传递给过滤器上的 acceptNode 方法。如果参数 "entities" 设置为 false，则把 EntityReference 节点的子节点传递给过滤器。注意，如参数 "entities" 所描述的那样，从不会丢弃未展开的实体引用节点，并且始终将它传递给过滤器。

解析文档期间，所有的有效性检查都像它出现在输入流上那样出现在源文档上，而不像在内存中构建它那样出现在 DOM 文档上。使用过滤器，内存中的文档可以是流上文档的子集，并且其有效性可能已受到了过滤的影响。

当将元素传递给过滤器方法时，所有的默认属性必须出现在这些元素上。所有其他默认内容也必须传递给过滤器方法。

DOM 应用程序不能引发过滤器中的异常。从过滤器中抛出异常产生的效果具有 DOM 实现依赖性。

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

字段摘要

static short	FILTER_ACCEPT 接受节点。
static short	FILTER_INTERRUPT 中断对文档的常规处理。
static short	FILTER_REJECT 拒绝节点及其子节点。
static short	FILTER_SKIP 跳过此单个节点。

方法摘要

short	acceptNode(Node nodeArg) 此方法将由解析器在完成对每个节点的解析后调用。
int	getWhatToShow() 告知 LSParser 将向方法 LSParserFilter.acceptNode 显示什么类型的节点。
short	startElement(Element elementArg) 解析器将在扫描完每个 Element 启动标记后，处理其余的 Element 之前调用此方法。

字段详细信息

FILTER_ACCEPT

static final short FILTER_ACCEPT

接受节点。

另请参见：

常量字段值

FILTER_REJECT

static final short FILTER_REJECT

拒绝节点及其子节点。

另请参见：

常量字段值

FILTER_SKIP

static final short FILTER_SKIP

跳过此单个节点。仍需考虑此节点的子节点。

另请参见：

常量字段值

FILTER_INTERRUPT

static final short FILTER_INTERRUPT

中断对文档的常规处理。

另请参见：

常量字段值

方法详细信息

startElement

short startElement(Element elementArg)

解析器将在扫描完每个 Element 启动标记后，处理其余的 Element 之前调用此方法。其目的是允许有效跳过包括任何子元素在内的元素。注意，仅将元素节点传递给 startElement 函数。
传递给 startElement 以便过滤的元素节点包括所有的 Element 属性，但不包括任何子节点。Element 还不能放构建的文档中适当的位置（它不能有父节点）。
startElement 过滤器函数可以访问或更改 Element 的属性。更改 Namespace 声明不会对解析器的名称空间解析产生任何影响。
为了提高效率，如果节点被接受，传递给过滤器的 Element 节点不能与实际放置于树中的节点是同一个节点。并且在文档中读取和过滤文档过程中，可以重新使用实际的节点（节点对象标识）。

参数：

elementArg - 新遇到的元素。此时将调用此方法，元素不完整 - 它将有其自己的属性，但没有子项。

返回：

• FILTER_ACCEPT 如果 Element 必须包括在要构建的 DOM 文档中。
• FILTER_REJECT 如果 Element 及其所有的子项必须拒绝。
• FILTER_SKIP 如果 Element 必须跳过。将把它所有的子项插入到跳过的 Element 节点位置。
• FILTER_INTERRUPT 如果过滤器想停止对文档的处理。中断对文档的处理将不再保证得到的 DOM 树是格式良好的 XML。拒绝 Element。

返回任何其他值都会导致未指定的行为。

acceptNode

short acceptNode(Node nodeArg)

此方法将由解析器在完成对每个节点的解析后调用。节点及其所有后代将存在并且是完整的。父节点也将存在，尽管它可能不是完整的，即它可能有尚未解析的附加子节点。从不将属性节点传递给此函数。
在此方法中，新节点可以随意修改 - 可以添加或移除子节点，修改文本节点等。此节点外面文档的其余部分的状态是没有定义的，并且尝试导航到或修改文档的其他任何部分产生的影响是未定义的。
为了验证解析器，将在过滤器进行任何修改之前检查原始文档。在过滤器执行的任何文档修改上都不进行有效性检查。
如果此新节点被拒绝，则解析器可能会重用该新节点及其所有的后代。

参数：

nodeArg - 新构建的元素。此时调用此方法，该元素是完整的 - 它具有其所有的子节点（和它们的字节点，以此类推）和属性，并且作为子节点连接到它的父节点。

返回：

• FILTER_ACCEPT 如果此 Node 必须包括在要构建的 DOM 文档中。
• FILTER_REJECT 如果 Node 及其所有的子节点必须被拒绝。
• FILTER_SKIP 如果 Node 必须跳过并且 Node 必须由 Node 的所有子节点代替。
• FILTER_INTERRUPT 如果过滤器想停止对文档的处理。中止对文档的处理将不再保证得到的 DOM 树是格式良好的 XML。Node 被接受，并且将成为最后一个得到完整解析的节点。

getWhatToShow

int getWhatToShow()

告知 LSParser 将向方法 LSParserFilter.acceptNode 显示什么类型的节点。如果没有将某个节点显示给使用此属性的过滤器，则该节点将自动包含在要构建的 DOM 文档中。有关对常量的定义请参见 NodeFilter。常量 SHOW_ATTRIBUTE、SHOW_DOCUMENT、SHOW_DOCUMENT_TYPE、SHOW_NOTATION、SHOW_ENTITY 和 SHOW_DOCUMENT_FRAGMENT 在此无意义。从不会将这些节点传递给 LSParserFilter.acceptNode。
此处使用的常量在 [DOM Level 2 Traversal and Range] 中定义。