模块 java.xml
包 org.xml.sax

接口 DocumentHandler

所有已知的实现类：
HandlerBase , ParserAdapter
@Deprecated (since ="1.5") public interface DocumentHandler
已弃用。
此接口已被 SAX2 ContentHandler 接口取代，其中包括命名空间支持。
接收一般文档事件的通知。

这是 SAX1 的主要事件处理接口；在 SAX2 中，它已被 ContentHandler 取代，它提供命名空间支持和跳过实体的报告。 SAX2 中包含此接口只是为了支持遗留的 SAX1 应用程序。

此界面中的事件顺序非常重要，它反映了文档本身中信息的顺序。例如，元素的所有内容（字符数据、处理指令和/或子元素）将按顺序出现在 startElement 事件和相应的 endElement 事件之间。

不想实现整个接口的应用程序编写者可以从 HandlerBase 派生一个类，该类实现默认功能；解析器编写者可以实例化 HandlerBase 以获得默认处理程序。应用程序可以使用解析器通过 setDocumentLocator 方法提供的 Locator 接口找到任何文档事件的位置。

自从：
1.4, SAX 1.0
参见：

  • 方法总结

    修饰符和类型
    方法
    描述
    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 解析器（虽然不是绝对要求）提供定位器：如果这样做，它必须在调用 DocumentHandler 接口中的任何其他方法之前通过调用此方法向应用程序提供定位器。

      定位器允许应用程序确定任何文档相关事件的结束位置，即使解析器没有报告错误。通常，应用程序会使用此信息来报告自己的错误（例如字符内容与应用程序的业务规则不匹配）。定位器返回的信息可能不足以用于搜索引擎。

      请注意，只有在调用此接口中的事件期间，定位器才会返回正确的信息。应用程序不应在任何其他时间尝试使用它。

      参数：
      locator - 可以返回任何 SAX 文档事件位置的对象。
      参见：

    • startDocument

      void startDocument() throws SAXException
      已弃用。
      接收文档开始的通知。

      SAX 解析器将仅调用此方法一次，在此接口或 DTDHandler 中的任何其他方法之前（setDocumentLocator 除外）。

      抛出：
      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

      void endElement(String  name) throws SAXException
      已弃用。
      接收元素结束的通知。

      SAX 解析器将在 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

      void ignorableWhitespace(char[] ch, int start, int length) throws SAXException
      已弃用。
      接收元素内容中可忽略空格的通知。

      验证解析器必须使用此方法来报告每个可忽略的空白块（请参阅 W3C XML 1.0 推荐，第 2.10 节）：如果非验证解析器能够解析和使用内容模型，则它们也可以使用此方法。

      SAX 解析器可能会在单个块中返回所有连续的空白，或者它们可能会将其分成几个块；但是，任何单个事件中的所有角色都必须来自同一个外部实体，以便定位器提供有用的信息。

      应用程序不得尝试读取指定范围之外的数组。

      参数：
      ch - 来自 XML 文档的字符。
      start - 数组中的起始位置。
      length - 要从数组中读取的字符数。
      抛出：
      SAXException - 任何 SAX 异常，可能包装另一个异常。
      参见：

    • 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 异常，可能包装另一个异常。