模块 java.xml
包 org.xml.sax

接口 XMLReader

所有已知的子接口：
XMLFilter
所有已知的实现类：
ParserAdapter , XMLFilterImpl
public interface XMLReader
使用回调读取 XML 文档的接口。

XMLReader 是 XML 解析器的 SAX2 驱动程序必须实现的接口。此接口允许应用程序设置和查询解析器中的功能和属性，注册事件处理程序以进行文档处理，并启动文档解析。

假定所有 SAX 接口都是同步的：parse 方法在解析完成之前不得返回，并且读者必须等待事件处理程序回调返回才能报告下一个事件。

此接口替换（现已弃用）SAX 1.0 Parser 接口。 XMLReader 接口包含两个对旧 Parser 接口的重要增强（以及一些次要的）：

  1. 它增加了一种查询和设置功能和属性的标准方法；和
  2. 它添加了命名空间支持，这是许多更高级别的 XML 标准所必需的。

有适配器可用于将 SAX1 解析器转换为 SAX2 XMLReader，反之亦然。

API 注意：
尽管它的名称如此，但此接口确实not 扩展了标准 Java Reader 接口，因为读取 XML 与读取字符数据是根本不同的活动。
自从：
1.4, SAX 2.0
参见：

  • 方法详情

    • getFeature

      boolean getFeature(String  name) throws SAXNotRecognizedException , SAXNotSupportedException
      查找功能标志的值。

      功能名称是任何完全限定的 URI。 XMLReader 可以识别特征名称但暂时无法返回其值。某些特征值可能仅在特定上下文中可用，例如解析之前、期间或之后。此外，某些特征值可能无法以编程方式访问。 （对于 SAX1 Parser 的适配器，没有独立于实现的方式来公开底层解析器是否正在执行验证、扩展外部实体等。）

      所有 XMLReader 都需要识别 http://xml.org/sax/features/namespaces 和 http://xml.org/sax/features/namespace-prefixes 功能名称。

      典型的用法是这样的：

       XMLReader r = new MySAXDriver();

             // try to activate validation
 try {
  r.setFeature("http://xml.org/sax/features/validation", true);
 } catch (SAXException e) {
  System.err.println("Cannot activate validation.");
 }

             // register event handlers
 r.setContentHandler(new MyContentHandler());
 r.setErrorHandler(new MyErrorHandler());

             // parse the first document
 try {
  r.parse("http://www.foo.com/mydoc.xml");
 } catch (IOException e) {
  System.err.println("I/O exception reading XML document");
 } catch (SAXException e) {
  System.err.println("XML exception reading document.");
 }

      实现者可以自由（并鼓励）使用建立在他们自己的 URI 上的名称来发明他们自己的特性。

      参数：
      name - 功能名称，它是一个完全限定的 URI。
      返回：
      特征的当前值（真或假）。
      抛出：
      SAXNotRecognizedException - 如果无法分配或检索特征值。
      SAXNotSupportedException - 当 XMLReader 识别特征名称但此时无法确定其值时。
      参见：

    • setFeature

      void setFeature(String  name, boolean value) throws SAXNotRecognizedException , SAXNotSupportedException
      设置功能标志的值。

      功能名称是任何完全限定的 URI。 XMLReader 可以公开一个特征值但不能更改当前值。一些特征值可能只在特定的上下文中是不可变的或可变的，例如在解析之前、期间或之后。

      所有 XMLReader 都需要支持将 http://xml.org/sax/features/namespaces 设置为 true 并将 http://xml.org/sax/features/namespace-prefixes 设置为 false。

      参数：
      name - 功能名称，它是一个完全限定的 URI。
      value - 特征的请求值（真或假）。
      抛出：
      SAXNotRecognizedException - 如果无法分配或检索特征值。
      SAXNotSupportedException - 当 XMLReader 识别功能名称但无法设置请求的值时。
      参见：

    • getProperty

      Object  getProperty(String  name) throws SAXNotRecognizedException , SAXNotSupportedException
      查找属性的值。

      属性名称是任何完全限定的 URI。 XMLReader 有可能识别属性名称但暂时无法返回其值。某些属性值可能仅在特定上下文中可用，例如解析之前、期间或之后。

      XMLReader 不需要识别任何特定的属性名称，尽管为 SAX2 记录了一个初始核心集。

      实现者可以自由（并鼓励）使用建立在他们自己的 URI 上的名称来发明他们自己的属性。

      参数：
      name - 属性名称，它是一个完全限定的 URI。
      返回：
      属性的当前值。
      抛出：
      SAXNotRecognizedException - 如果无法分配或检索属性值。
      SAXNotSupportedException - 当 XMLReader 识别属性名称但此时无法确定其值时。
      参见：

    • setProperty

      void setProperty(String  name, Object  value) throws SAXNotRecognizedException , SAXNotSupportedException
      设置属性的值。

      属性名称是任何完全限定的 URI。 XMLReader 可以识别属性名称但无法更改当前值。某些属性值可能仅在特定上下文中不可变或可变，例如在解析之前、期间或之后。

      XMLReader 不需要识别设置任何特定的属性名称，尽管核心集由 SAX2 定义。

      此方法也是设置扩展处理程序的标准机制。

      参数：
      name - 属性名称，它是一个完全限定的 URI。
      value - 请求的属性值。
      抛出：
      SAXNotRecognizedException - 如果无法分配或检索属性值。
      SAXNotSupportedException - 当 XMLReader 识别属性名称但无法设置请求的值时。

    • setEntityResolver

      void setEntityResolver(EntityResolver  resolver)
      允许应用程序注册实体解析器。

      如果应用程序没有注册实体解析器，XMLReader 将执行它自己的默认解析。

      应用程序可以在解析过程中注册一个新的或不同的解析器，SAX 解析器必须立即开始使用新的解析器。

      参数：
      resolver - 实体解析器。
      参见：

    • getEntityResolver

      EntityResolver  getEntityResolver()
      返回当前实体解析器。
      返回：
      当前的实体解析器，如果没有注册则为 null。
      参见：

    • setDTDHandler

      void setDTDHandler(DTDHandler  handler)
      允许应用程序注册 DTD 事件处理程序。

      如果应用程序没有注册 DTD 处理程序，则 SAX 解析器报告的所有 DTD 事件都将被忽略。

      应用程序可以在解析过程中注册一个新的或不同的处理程序，SAX 解析器必须立即开始使用新的处理程序。

      参数：
      handler - DTD 处理程序。
      参见：

    • getDTDHandler

      DTDHandler  getDTDHandler()
      返回当前的 DTD 处理程序。
      返回：
      当前的 DTD 处理程序，如果没有注册则为 null。
      参见：

    • setContentHandler

      void setContentHandler(ContentHandler  handler)
      允许应用程序注册内容事件处理程序。

      如果应用程序没有注册内容处理程序，则 SAX 解析器报告的所有内容事件都将被忽略。

      应用程序可以在解析过程中注册一个新的或不同的处理程序，SAX 解析器必须立即开始使用新的处理程序。

      参数：
      handler - 内容处理程序。
      参见：

    • getContentHandler

      ContentHandler  getContentHandler()
      返回当前内容处理程序。
      返回：
      当前内容处理程序，如果没有注册则为 null。
      参见：

    • setErrorHandler

      void setErrorHandler(ErrorHandler  handler)
      允许应用程序注册错误事件处理程序。

      如果应用程序没有注册错误处理程序，SAX 解析器报告的所有错误事件都将被忽略；但是，正常处理可能不会继续。强烈建议所有 SAX 应用程序实现错误处理程序以避免意外错误。

      应用程序可以在解析过程中注册一个新的或不同的处理程序，SAX 解析器必须立即开始使用新的处理程序。

      参数：
      handler - 错误处理程序。
      参见：

    • getErrorHandler

      ErrorHandler  getErrorHandler()
      返回当前的错误处理程序。
      返回：
      当前错误处理程序，如果未注册则为 null。
      参见：

    • parse

      void parse(InputSource  input) throws IOException , SAXException
      解析 XML 文档。

      应用程序可以使用此方法指示 XML 阅读器开始解析来自任何有效输入源（字符流、字节流或 URI）的 XML 文档。

      应用程序在解析过程中可能不会调用此方法（它们应该为每个嵌套的 XML 文档创建一个新的 XMLReader）。解析完成后，应用程序可以重用相同的 XMLReader 对象，可能使用不同的输入源。 XMLReader 对象的配置（例如处理程序绑定和为功能标志和属性建立的值）在解析完成时不会改变，除非配置的该方面的定义明确指定其他行为。 （例如，特征标志或属性公开正在解析的文档的特征。）

      在解析期间，XMLReader 将通过已注册的事件处理程序提供有关 XML 文档的信息。

      此方法是同步的：直到解析结束才会返回。如果客户端应用程序想要提前终止解析，它应该抛出一个异常。

      参数：
      input - XML 文档顶层的输入源。
      抛出：
      SAXException - 任何 SAX 异常，可能包装另一个异常。
      IOException - 来自解析器的 IO 异常，可能来自应用程序提供的字节流或字符流。
      参见：

    • parse

      void parse(String  systemId) throws IOException , SAXException
      从系统标识符 (URI) 解析 XML 文档。

      此方法是从系统标识符读取文档的常见情况的快捷方式。它完全等同于以下内容：

       parse(new InputSource(systemId));

      如果系统标识符是一个 URL，它必须在传递给解析器之前由应用程序完全解析。

      参数：
      systemId - 系统标识符 (URI)。
      抛出：
      SAXException - 任何 SAX 异常，可能包装另一个异常。
      IOException - 来自解析器的 IO 异常，可能来自应用程序提供的字节流或字符流。
      参见：