模块 java.xml
包 org.xml.sax

接口 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
参见：

  • 方法详情

    • setDocumentLocator

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

      强烈鼓励 SAX 解析器（虽然不是绝对要求）提供定位器：如果这样做，它必须在调用 ContentHandler 接口中的任何其他方法之前通过调用此方法向应用程序提供定位器。

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

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

      参数：
      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 命名空间映射的范围。

      来自此事件的信息对于正常的命名空间处理不是必需的：SAX XML 阅读器将在http://xml.org/sax/features/namespaces 特性是时自动替换元素和属性名称的前缀true（默认值）。

      然而，在某些情况下，当应用程序需要在字符数据或属性值中使用前缀时，它们无法安全地自动扩展； 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特性：

      • 当命名空间属性是时，需要命名空间 URI 和本地名称true（默认值），并且在命名空间属性为false（如果指定一个，则两者都必须）；
      • 当命名空间前缀属性为true，并且在命名空间前缀属性为false（默认值）。

      请注意，提供的属性列表将仅包含具有显式值（指定或默认）的属性：#IMPLIED 属性将被省略。仅当 http://xml.org/sax/features/namespace-prefixes 属性为真时，属性列表将包含用于命名空间声明的属性（xmlns* 属性）（默认情况下为假，对真值的支持是可选的）。

      与 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 值。有两种重要的情况会发生这种情况，因为字符不能仅用 16 位来表示。在一种情况下，字符在 Surrogate Pair 中表示，使用两个特殊的 Unicode 值。这些字符在所谓的“星界平面”中，代码点在 U+FFFF 之上。第二种情况涉及复合字符，例如与一个或多个重音字符组合的基本字符。

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

      请注意，某些解析器将使用 ignorableWhitespace 方法而不是此方法报告元素内容中的空格（验证解析器 must 会这样做）。

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