模块  java.xml
软件包  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.
    接收一般文件事件的通知。
    This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

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

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

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

    从以下版本开始：
    1.4，SAX 1.0
    另请参见：
    Parser.setDocumentHandler(org.xml.sax.DocumentHandler) ， Locator ， HandlerBase

    • 方法详细信息

      • setDocumentLocator

        void setDocumentLocator​(Locator locator)
        Deprecated.
        接收用于查找SAX文档事件原点的对象。

        强烈建议SAX解析器（尽管不是绝对必需）提供定位器：如果它这样做，它必须通过在调用DocumentHandler接口中的任何其他方法之前调用此方法来向应用程序提供定位器。

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

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

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

      • 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(java.lang.String) ， AttributeList

      • 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解析器可以在一个块中返回所有连续的字符数据，或者它们可以将它分成几个块; 但是，任何单个事件中的所有字符都必须来自同一个外部实体，以便Locator提供有用的信息。

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

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

        参数
        ch - XML文档中的字符。
        start - 数组中的起始位置。
        length - 要从阵列中读取的字符数。
        异常
        SAXException - 任何SAX异常，可能包含另一个异常。
        另请参见：
        ignorableWhitespace(char[], int, int) ， Locator

      • ignorableWhitespace

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

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

        SAX解析器可以在一个块中返回所有连续的空格，或者它们可以将它分成几个块; 但是，任何单个事件中的所有字符都必须来自同一个外部实体，以便Locator提供有用的信息。

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

        参数
        ch - XML文档中的字符。
        start - 数组中的起始位置。
        length - 要从阵列中读取的字符数。
        异常
        SAXException - 任何SAX异常，可能包含另一个异常。
        另请参见：
        characters(char[], int, int)

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