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] 中定義。