Module java.xml
Package org.xml.sax

Interface ContentHandler

所有已知的子接口:
TemplatesHandler, TransformerHandler
所有已知的实现类:
DefaultHandler, DefaultHandler2, ValidatorHandler, XMLFilterImpl, XMLReaderAdapter
public interface ContentHandler
接收文档的逻辑内容通知。

这是大多数SAX应用程序实现的主要接口: 如果应用程序需要被通知基本解析事件，它实现这个接口并使用setContentHandler方法向SAX解析器注册一个实例。解析器使用该实例报告基本与文档相关的事件，如元素的开始和结束以及字符数据。

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

此接口类似于现在已弃用的SAX 1.0 DocumentHandler接口，但它增加了对命名空间的支持以及报告跳过的实体（在非验证XML处理器中）。

实现者应该注意，java.net包中也有一个ContentHandler类; 这意味着这样做可能不是一个好主意

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

事实上，“import ...*”通常是懒散编程的标志，因此用户应该将其视为一种特性而不是错误。

自从:
1.4, SAX 2.0
参见:

  • Method Details

    • setDocumentLocator

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

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

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

      请注意，只有在调用SAX事件回调之后的startDocument返回之后且在调用endDocument之前，定位器才会返回正确的信息。应用程序不应在任何其他时间尝试使用它。

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

    • startDocument

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

      SAX解析器将在任何其他事件回调之前（除了setDocumentLocator之外）仅调用此方法一次。

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

    • declaration

      default void declaration(String version, String encoding, String standalone) throws SAXException
      接收XML声明通知。
      实现要求:
      SAX API中的默认实现是什么都不做。
      参数:
      version - 输入文档中的版本字符串，如果未指定则为null
      encoding - 输入文档中的编码字符串，如果未指定则为null
      standalone - 输入文档中的独立字符串，如果未指定则为null
      抛出:
      SAXException - 如果应用程序想要报告错误或中断解析过程
      自从:
      14

    • endDocument

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

      此方法由解析器调用，以表示已成功完成解析过程并到达文档末尾。事件后，解析器将控制返回给应用程序。

      API注释:
      在发生致命错误的情况下，解析器可能选择使用SAXException停止解析过程，在这种情况下，此方法将永远不会被调用。请参阅ErrorHandler.fatalError(org.xml.sax.SAXParseException)。
      抛出:
      SAXException - 任何SAX异常，可能包装另一个异常
      参见:

    • 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

      void endPrefixMapping(String prefix) throws SAXException
      结束前缀-URI映射的范围。

      有关详细信息，请参阅startPrefixMapping。这些事件将始终在相应的endElement事件之后立即发生，但不保证endPrefixMapping事件的顺序。

      参数:
      prefix - 正在映射的前缀。当默认映射范围结束时，这是空字符串。
      抛出:
      SAXException - 客户端在处理过程中可能抛出异常
      参见:

    • 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属性将被省略。属性列表将仅包含用于命名空间声明（xmlns*属性）的属性，仅当http://xml.org/sax/features/namespace-prefixes属性为true时（默认为false，并且对true值的支持是可选的）。

      与characters()类似，属性值可能包含需要多个char值的字符。

      参数：
      uri - 命名空间URI，如果元素没有命名空间URI或未执行命名空间处理，则为空字符串
      localName - 本地名称（无前缀），如果未执行命名空间处理，则为空字符串
      qName - 限定名称（带前缀），如果不可用限定名称，则为空字符串
      atts - 附加到元素的属性。如果没有属性，则应该是一个空的Attributes对象。startElement返回后，此对象的值是未定义的
      抛出：
      SAXException - 任何SAX异常，可能包装另一个异常
      参见：

    • 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值。这些字符位于所谓的“星际平面”，其代码点高于U+FFFF。第二种情况涉及复合字符，例如基本字符与一个或多个重音字符组合。

      您的代码不应假定使用char一次性习语的算法将以字符单位工作；在某些情况下，它们将拆分字符。这在XML允许任意字符的地方（例如属性值、处理指令数据和注释以及从此方法报告的数据）以及Java代码操作国际化文本时是相关的。这也通常与Java代码操作国际化文本相关；这个问题并不是XML独有的。

      请注意，一些解析器将使用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节）。

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