org.xml.sax
介面 ContentHandler

所有已知子介面：

TemplatesHandler, TransformerHandler, UnmarshallerHandler

所有已知實作類別：

DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter

public interface ContentHandler

接收文檔邏輯內容的通知。

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

這是一個大多數 SAX 應用程序實施的主要介面：如果需要通知應用程序基本解析事件，則它將實作此介面並且使用 setContentHandler 方法，向 SAX 解析器註冊一個實例。解析器將使用該實例報告與基本文檔相關的事件，如啟動和終止元素與字元資料。

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

此介面與現在不推薦使用的 SAX 1.0 DocumentHandler 介面相似，但它增加了對名稱空間和報告跳過的實體（在非驗證的 XML 處理器中）的支持。

實作者應該注意，在 java.net 套件中還有一個 ContentHandler 類別；這意味著以下實作方法可能並非明智之舉

import java.net.*;
 import org.xml.sax.*;
 

實際上，不管怎樣 "import ...*" 通常標誌不簡潔的程式，因此，使用者應該將此作為一種功能而不是錯誤。

從以下版本開始：

SAX 2.0

另請參見：

XMLReader, DTDHandler, ErrorHandler

方法摘要

void	characters(char[] ch, int start, int length) 接收字元資料的通知。
void	endDocument() 接收文檔的結尾的通知。
void	endElement(String uri, String localName, String qName) 接收元素結束的通知。
void	endPrefixMapping(String prefix) 結束前綴 URI 範圍的映射。
void	ignorableWhitespace(char[] ch, int start, int length) 接收元素內容中可忽略的空白的通知。
void	processingInstruction(String target, String data) 接收處理指令的通知。
void	setDocumentLocator(Locator locator) 接收用來尋找 SAX 文檔事件起源的物件。
void	skippedEntity(String name) 接收跳過的實體的通知。
void	startDocument() 接收文檔的開始的通知。
void	startElement(String uri, String localName, String qName, Attributes atts) 接收元素開始的通知。
void	startPrefixMapping(String prefix, String uri) 開始前綴 URI 名稱空間範圍映射。

方法詳細資訊

setDocumentLocator

void setDocumentLocator(Locator locator)

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

強烈建議（但不是絕對需要）使用 SAX 解析器來提供定位器：如果是這樣，則必須在調用 ContentHandler 介面中的任何其他方法之前調用此方法為應用程序提供定位器。

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

注意，該定位器僅在調用 SAX 事件回調期間,在 startDocument 返回之後，調用 endDocument 之前，返回正確的資訊。應用程序不應該嘗試在任何時間都使用它。

參數：

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

另請參見：

Locator

startDocument

void startDocument()
                   throws SAXException

接收文檔的開始的通知。

在其他任何事件回調（不包括 setDocumentLocator）之前，SAX 解析器僅調用此方法一次。

拋出：

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

另請參見：

endDocument()

endDocument

void endDocument()
                 throws SAXException

接收文檔的結尾的通知。

在此方法的說明和 ErrorHandler.fatalError(org.xml.sax.SAXParseException) 的說明之間存在著明顯的衝突。在未來的主版本中解決這一不明確問題之後，關於解析器報告 fatalError() 或拋出異常後是否調用 endDocument() 這一點，客戶將會十分明確。

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

拋出：

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

另請參見：

startDocument()

startPrefixMapping

void startPrefixMapping(String prefix,
                        String uri)
                        throws SAXException

開始前綴 URI 名稱空間範圍映射。

此事件的資訊對於常規的名稱空間處理並非必需：當 http://xml.org/sax/features/namespaces 功能為 true（預設）時，SAX XML 讀取器將自動替換元素和屬性名稱的前綴。

但是，有這樣幾種情況，應用程序需要在字元資料或屬性值中使用前綴，但在這裡，前綴不能自動地安全擴展；必要時，start/endPrefixMapping 事件將為應用程序提供所需資訊，以便應用程序本身可在這些上下文中擴展前綴。

注意，不能保證 start/endPrefixMapping 事件相互之間能夠正確地巢狀：所有的 startPrefixMapping 事件將在相應的 startElement 事件之前立即發生，所有的 endPrefixMapping 事件將在相應的 endElement 事件之後立即發生，但在其他情況下不能保證其順序。

對於 "xml" 前綴，永遠不應有 start/endPrefixMapping 事件，因為它是預宣告的和不可改變。

參數：

prefix - 宣告的名稱空間前綴。對於沒有前綴的預設元素名稱空間，使用空字元串。

uri - 將前綴映射到的名稱空間 URI

拋出：

SAXException - 客戶端可能會在處理期間拋出一個異常

另請參見：

endPrefixMapping(java.lang.String), startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)

endPrefixMapping

void endPrefixMapping(String prefix)
                      throws SAXException

結束前綴 URI 範圍的映射。

詳細資訊請參閱 startPrefixMapping。這些事件將始終在相應的 endElement 事件之後立即發生，但在其他情況下 endPrefixMapping 事件的順序不能保證。

參數：

prefix - 被映射的前綴。當預設的映射範圍結束時，這是一個空字元串。

拋出：

SAXException - 客戶端可能會在處理期間拋出一個異常

另請參見：

startPrefixMapping(java.lang.String, java.lang.String), endElement(java.lang.String, java.lang.String, java.lang.String)

startElement

void startElement(String uri,
                  String localName,
                  String qName,
                  Attributes atts)
                  throws SAXException

接收元素開始的通知。

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

此事件允許每個元素最多有以下三個名稱元件：

1. 名稱空間 URI；
2. 本地名稱；和
3. 限定（前綴）名。

可以提供它們中的部分或全部，具體如何取決於 http://xml.org/sax/features/namespaces 和 http://xml.org/sax/features/namespace-prefixes 屬性的值：

• 當名稱空間屬性為 true（預設）時，名稱空間 URI 和本地名稱是必需項，當名稱空間屬性為 false 時，則為可選項（如果指定一個值，兩個都必須指定）；
• 當名稱空間前綴屬性為 true 時，限定名是必需項，當名稱空間前綴屬性為 false(預設值）時，則為可選項。

注意，所提供的屬性列表僅包括具有顯式值（指定的或預設的）的屬性：將忽略 #IMPLIED 屬性。僅在 http://xml.org/sax/features/namespace-prefixes 屬性為 true （預設情況下為 false，並且對 true 值的支持是可選項）時屬性列表才包括用於名稱空間宣告（xmlns* 屬性）的屬性。

與 characters() 一樣，屬性值可以具有需要不止一個 char 值的字元。

參數：

uri - 名稱空間 URI，如果元素沒有名稱空間 URI，或者未執行名稱空間處理，則為空字元串

localName - 本地名稱（不帶前綴），如果未執行名稱空間處理，則為空字元串

qName - 限定名（帶有前綴），如果限定名不可用，則為空字元串

atts - 連接到元素上的屬性。如果沒有屬性，則它將是空 Attributes 物件。在 startElement 返回後，此物件的值是未定義的

拋出：

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

另請參見：

endElement(java.lang.String, java.lang.String, java.lang.String), Attributes, AttributesImpl

endElement

void endElement(String uri,
                String localName,
                String qName)
                throws SAXException

接收元素結束的通知。

SAX 解析器會在 XML 文檔中每個元素的末尾調用此方法；對於每個 endElement 事件都將有相應的 startElement 事件（即使該元素為空時）。

有關名稱的資訊，請參見 startElement。

參數：

uri - 名稱空間 URI，如果元素沒有名稱空間 URI，或者未執行名稱空間處理，則為空字元串

localName - 本地名稱（不帶前綴），如果未執行名稱空間處理，則為空字元串

qName - 限定的 XML 名稱（帶前綴），如果限定名不可用，則為空字元串

拋出：

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

characters

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

接收字元資料的通知。

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

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

單獨的字元可以由不止一個 Java char 值組成。由於不能僅用十六位來表示字元，所以發生此情況的重要情形有兩種。一種情形是，字元用代理項對 表示，使用兩個特殊的 Unicode 值。此類別字元在所謂的 "Astral Planes" 中，程式碼點在 U+FFFF 之上。另一種情形涉及到復合字元，如由一個或多個重音字元構成的基本字元。

編寫程式碼時不能假定一次讀入一個 char 的演算法將適用於字元單元；在某些情況下這些演算法將拆分一些字元。這與在什麼情況下 XML 允許有任意字元（如屬性值、處理指令資料、註解以及從此方法中報告的資料）相關。通常還與 Java 程式碼控制國際化的文本時相關；該問題不是 XML 獨有的。

注意，有些解析器將使用 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 Recommendation”中的 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 節）。

與 characters() 一樣，處理指令資料可以具有需要不止一個 char 值的字元。

參數：

target - 處理指令目標

data - 處理指令資料，如果未提供，則為 null。該資料不包括將其與目標分開的任何空白

拋出：

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

skippedEntity

void skippedEntity(String name)
                   throws SAXException

接收跳過的實體的通知。將不為標記結構（如元素開始標記或標記宣告）內的實體參考調用此方法。（XML 建議書要求報告所跳過的外部實體。SAX 還報告內部實體擴展 / 非擴展，但不包括在標記結構內部。）

解析器將在每次跳過實體時調用此方法。如果非驗證處理器尚未看到宣告，則可以跳過實體（例如，因為該實體在外部 DTD 子集中宣告）。所有的處理器都可以跳過外部實體，但具體情況取決於 http://xml.org/sax/features/external-general-entities 和 http://xml.org/sax/features/external-parameter-entities 屬性的值。

參數：

name - 所跳過的實體的名稱。如果它是參數實體，則名稱將以 '%' 開頭，如果它是外部 DTD 子集，則將是字元串 "[dtd]"

拋出：

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