org.xml.sax
接口 DocumentHandler

所有已知实现类：

HandlerBase, ParserAdapter

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

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 异常，可能包装另外的异常。

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。