Module java.xml
Package org.xml.sax

Interface DocumentHandler

所有已知的实现类:
HandlerBase, ParserAdapter
@Deprecated(since="1.5") public interface DocumentHandler
Deprecated.
This interface has been replaced by the SAX2 ContentHandler interface, which includes Namespace support.
接收一般文档事件的通知。

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

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

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

自从:
1.4, SAX 1.0
参见:

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    已弃用。
    接收元素开始的通知。

  • Method Details

    • setDocumentLocator

      void setDocumentLocator(Locator locator)
      Deprecated.
      接收用于定位SAX文档事件起源的对象。

      SAX解析器强烈建议（虽然不是绝对必需）提供一个定位器：如果提供了定位器，解析器必须在调用此方法之前通过调用此方法将定位器提供给应用程序，而不调用DocumentHandler接口中的其他方法。

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

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

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

    • startDocument

      void startDocument() throws SAXException
      Deprecated.
      接收文档开始的通知。

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

      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常。

    • endDocument

      void endDocument() throws SAXException
      Deprecated.
      接收文档结束的通知。

      SAX解析器将仅调用此方法一次，并且它将是解析过程中调用的最后一个方法。解析器在放弃解析（因为不可恢复的错误）或达到输入结束之前不应调用此方法。

      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常。

    • startElement

      void startElement(String name, AttributeList atts) throws SAXException
      Deprecated.
      接收元素开始的通知。

      解析器将在XML文档中每个元素的开头调用此方法；每个startElement()事件都将有一个相应的endElement()事件（即使元素为空）。在相应的endElement()事件之前，将按顺序报告所有元素内容。

      如果元素名称具有命名空间前缀，则前缀仍将附加。请注意，提供的属性列表将仅包含具有显式值（指定或默认）的属性：#IMPLIED属性将被省略。

      参数:
      name - 元素类型名称。
      atts - 元素附加的属性（如果有）。
      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常。
      参见:

    • endElement

      void endElement(String name) throws SAXException
      Deprecated.
      接收元素结束的通知。

      SAX解析器将在XML文档中每个元素的结尾调用此方法；每个endElement()事件都将有一个相应的startElement()事件（即使元素为空）。

      如果元素名称具有命名空间前缀，则前缀仍将附加到名称。

      参数:
      name - 元素类型名称
      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常。

    • characters

      void characters(char[] ch, int start, int length) throws SAXException
      Deprecated.
      接收字符数据的通知。

      解析器将调用此方法来报告每个字符数据块。SAX解析器可以将所有连续字符数据放在一个块中，也可以将其分成几个块；但是，任何单个事件中的所有字符必须来自同一外部实体，以便定位器提供有用信息。

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

      请注意，一些解析器将使用ignorableWhitespace()方法报告空格而不是此方法（验证解析器必须这样做）。

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

    • ignorableWhitespace

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

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

      SAX解析器可以将所有连续空格放在一个块中，也可以将其分成几个块；但是，任何单个事件中的所有字符必须来自同一外部实体，以便定位器提供有用信息。

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

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

    • processingInstruction

      void processingInstruction(String target, String data) throws SAXException
      Deprecated.
      接收处理指令的通知。

      解析器将为找到的每个处理指令调用此方法：请注意，处理指令可能出现在主文档元素之前或之后。

      SAX解析器不应使用此方法报告XML声明（XML 1.0，第2.8节）或文本声明（XML 1.0，第4.3.1节）。

      参数:
      target - 处理指令目标。
      data - 处理指令数据，如果未提供则为null。
      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常。