org.xml.sax
介面 DocumentHandler

所有已知實作類別：

HandlerBase, ParserAdapter

已過時。 此介面已經被 SAX2 ContentHandler 介面取代，後者包括名稱空間支持。

public interface DocumentHandler

接收常規文檔事件的通知。

此模組（包括源程式碼和文檔）在公共域中，同時 沒有擔保。有關更多資訊，請參閱http://www.saxproject.org。

這是一個 SAX1 的主事件處理介面；在 SAX2 中，它已經被 ContentHandler 所取代，後者提供了名稱空間支持和對跳過的實體的報告。此介面包括在 SAX2 中，僅支持以前的 SAX1 應用程序。

在此介面中的事件順序非常重要，它本身可鏡像文檔中資訊的順序。例如，在 startElement 事件與相應的 endElement 事件之間，元素的所有內容（字元資料、處理指令和/ 或子元素）都將以一定順序出現。

不想實施完整介面的應用程序編寫者可以從 HandlerBase 派生出一個類別， HandlerBase 實作預設的功能；解析器編寫者可以通過實例化 HandlerBase 來獲取預設的處理程序。應用程序可以使用由解析器通過 setDocumentLocator 方法提供的 Locator 介面尋找任何文檔事件的位置。

從以下版本開始：

SAX 1.0

另請參見：

Parser.setDocumentHandler(org.xml.sax.DocumentHandler), Locator, HandlerBase

方法摘要

void	characters(char[] ch, int start, int length) 已過時。 接收字元資料的通知。
void	endDocument() 已過時。 接收文檔結束的通知。
void	endElement(String name) 已過時。 接收元素結束的通知。
void	ignorableWhitespace(char[] ch, int start, int length) 已過時。 接收元素內容中可忽略的空白的通知。
void	processingInstruction(String target, String data) 已過時。 接收處理指令的通知。
void	setDocumentLocator(Locator locator) 已過時。 接收用來尋找 SAX 文檔事件起源的物件。
void	startDocument() 已過時。 接收文檔的開始的通知。
void	startElement(String name, AttributeList atts) 已過時。 接收元素開始的通知。

方法詳細資訊

setDocumentLocator

void setDocumentLocator(Locator locator)

已過時。

接收用來尋找 SAX 文檔事件起源的物件。

強烈建議（但並非必須）使用 SAX 解析器來提供定位器：如果使用 SAX 解析器，則必須在調用 DocumentHandler 介面中的任何其他方法之前調用此方法來為應用程序提供定位器。

定位器允許應用程序確定任何與文檔相關的事件的終止位置，即便是解析器不報告錯誤也是如此。通常情況下，應用程序將使用此資訊報告它自己的錯誤（例如與應用程序的業務規則不比對的字元內容）。由定位器返回的資訊可能不足以供搜尋引擎使用。

注意，定位器僅在調用此介面中的事件時返回正確的資訊。應用程序不應嘗試在任何其他時間使用定位器。

參數：

locator - 可以返回任何 SAX 文檔事件位置的物件。

另請參見：

Locator

startDocument

void startDocument()
                   throws SAXException

已過時。

接收文檔的開始的通知。

在調用此介面或 DTDHandler 中的其他任何方法（setDocumentLocator 方法除外）之前，SAX 解析器僅調用此方法一次。

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。

endDocument

void endDocument()
                 throws SAXException

已過時。

接收文檔結束的通知。

SAX 解析器僅調用此方法一次，並且它將是解析期間最後調用的方法。直到解析器放棄解析（由於不可恢復的錯誤）或到達輸入的結尾時，它才可以調用此方法。

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。

startElement

void startElement(String name,
                  AttributeList atts)
                  throws SAXException

已過時。

接收元素開始的通知。

解析器在 XML 文檔中的每個元素的開始調用此方法；對於每個 startElement() 事件都將有相應的 endElement() 事件（即使該元素為空時）。所有元素內容都將在相應的 endElement() 事件之前順序地報告。

如果元素名稱具有名稱空間前綴，則仍帶上前綴。注意，所提供的屬性列表僅包括具有顯式值（指定的或預設的）的屬性：將忽略 #IMPLIED 屬性。

參數：

name - 元素型別名稱。

atts - 附加到元素的屬性（如果有）。

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。

另請參見：

endElement(java.lang.String), AttributeList

endElement

void endElement(String name)
                throws SAXException

已過時。

接收元素結束的通知。

解析器會在 XML 文檔中的每個元素結束時調用此方法；對於每個 endElement() 事件都將有相應的 startElement() 事件（即便是該元素為空時也是如此）。

如果元素名稱具有名稱空間前綴，則仍會將該前綴附加到該名稱。

參數：

name - 元素型別名稱

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。

characters

void characters(char[] ch,
                int start,
                int length)
                throws SAXException

已過時。

接收字元資料的通知。

解析器將調用此方法來報告字元資料的每個存儲塊。SAX 解析器能夠用單個存儲塊返回所有的連續字元資料，或者可以將該資料拆分成幾個存儲塊；但是，任何單個事件中的全部字元都必須來自同一個外部實體，以便定位器能夠提供有用的資訊。

應用程序不能嘗試在指定的範圍外從陣列中讀取資料。

注意，有些解析器使用 ignorableWhitespace() 方法報告空白，而不是此方法（驗證解析器必須這樣做）。

參數：

ch - XML 文檔的字元。

start - 在陣列中的開始位置。

length - 從陣列中讀取的字元個數。

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。

另請參見：

ignorableWhitespace(char[], int, int), Locator

ignorableWhitespace

void ignorableWhitespace(char[] ch,
                         int start,
                         int length)
                         throws SAXException

已過時。

接收元素內容中可忽略的空白的通知。

驗證解析器必須使用此方法來報告每塊可忽略的空白（請參閱“W3C XML 1.0 建議書”中的 2.10 節）：如果非驗證解析器能夠解析和使用內容模型，則這些非驗證解析器也可以使用此方法。

SAX 解析器能夠用單個存儲塊返回所有的連續空白，或者可以將該資料拆分成幾個存儲塊；但是，任何單個事件中的全部字元都必須來自同一個外部實體，以便定位器能夠提供有用的資訊。

應用程序不能嘗試在指定的範圍外從陣列中讀取資料。

參數：

ch - XML 文檔的字元。

start - 在陣列中的開始位置。

length - 從陣列中讀取的字元個數。

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。

另請參見：

characters(char[], int, int)

processingInstruction

void processingInstruction(String target,
                           String data)
                           throws SAXException

已過時。

接收處理指令的通知。

解析器將為找到的每個處理指令調用一次此方法：注意，處理指令可以出現在主要文檔元素的前面或後面。

SAX 解析器始終不得使用此方法報告 XML 宣告（XML 1.0 的 2.8 節）或文本宣告（XML 1.0 的 4.3.1 節）。

參數：

target - 處理指令目標。

data - 處理指令資料，如果未提供，則為 null。

拋出：

SAXException - 任何 SAX 異常，可能包裹另外的異常。