Module java.xml
Package org.xml.sax

Interface 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注释:
尽管它的名称是这样，但该接口并未扩展标准Java Reader接口，因为读取XML是一种与读取字符数据根本不同的活动。
自从:
1.4, SAX 2.0
另请参阅:

  • Method Details

    • 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 {
   r.setFeature("http://xml.org/sax/features/validation", true);
 } catch (SAXException e) {
   System.err.println("无法激活验证。");
 }

                         // 注册事件处理程序
 r.setContentHandler(new MyContentHandler());
 r.setErrorHandler(new MyErrorHandler());

                         // 解析第一个文档
 try {
   r.parse("http://www.foo.com/mydoc.xml");
 } catch (IOException e) {
   System.err.println("读取XML文档时发生I/O异常");
 } catch (SAXException e) {
   System.err.println("读取文档时发生XML异常。");
 }

      实现者可以自由（并且鼓励）发明自己的特性，使用基于其自己URI的名称。

      参数:
      name - 特性名称，即完全限定的URI。
      返回:
      特性的当前值（true或false）。
      抛出:
      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 - 特性的请求值（true或false）。
      抛出:
      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异常，可能来自应用程序提供的字节流或字符流。
      参见: