org.xml.sax

接口
类
异常

org.xml.sax
接口 XMLReader

所有已知子接口：
XMLFilter
所有已知实现类：
ParserAdapter, XMLFilterImpl 
public interface XMLReader

用于使用回调读取 XML 文档的接口。

此模块（包括源代码和文档）在公共域中，同时 没有担保。有关更多信息，请参阅 http://www.saxproject.org。

注：不管其名称如何，此接口不 扩展标准的 Java Reader 接口，因为读取 XML 是一个与读取字符数据完全不同的活动。

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

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

此接口取代了（现在不推荐） SAX 1.0 Parser 接口。与旧的解析器接口（和某些监控器接口）相比，XMLReader 接口具有两大重要增强：

  1. 它增加了查询和设置功能和属性的标准方法；并且
  2. 增加了对名称空间的支持，这是许多高层的 XML 标准所必需的。

存在将 SAX1 解析器转换为 SAX2 XMLReader 的适配器并且反之亦然。

从以下版本开始：
SAX 2.0
另请参见：
XMLFilter, ParserAdapter, XMLReaderAdapter

方法摘要
 ContentHandler getContentHandler()
          返回当前的内容处理程序。
 DTDHandler getDTDHandler()
          返回当前的 DTD 处理程序。
 EntityResolver getEntityResolver()
          返回当前的实体解析器。
 ErrorHandler getErrorHandler()
          返回当前的错误处理程序。
 boolean getFeature(String name)
          查找功能标志的值。
 Object getProperty(String name)
          查找属性的值。
 void parse(InputSource input)
          解析 XML 文档。
 void parse(String systemId)
          从系统标识符 (URI) 解析 XML 文档。
 void setContentHandler(ContentHandler handler)
          允许应用程序注册内容事件处理程序。
 void setDTDHandler(DTDHandler handler)
          允许应用程序注册 DTD 事件处理程序。
 void setEntityResolver(EntityResolver resolver)
          允许应用程序注册实体解析器。
 void setErrorHandler(ErrorHandler handler)
          允许应用程序注册错误事件处理程序。
 void setFeature(String name, boolean value)
          设置功能标志的值。
 void setProperty(String name, Object value)
          设置属性的值。
 

方法详细信息

getFeature

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

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

要求所有的 XMLReaders 都能识别 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。
返回：
该功能的当前值（true 或 false）。
抛出：
SAXNotRecognizedException - 如果功能值不能分配或检索。
SAXNotSupportedException - 当 XMLReader 能够识别功能名称但此时却无法确定其值时。
另请参见：
setFeature(java.lang.String, boolean)

setFeature

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

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

要求所有的 XMLReaders 支持把 http://xml.org/sax/features/namespaces 设置为 true，把 http://xml.org/sax/features/namespace-prefixes 设置为 false。

参数：
name - 功能名称，它是一个完全限定 URI。
value - 请求的功能值（true 或 false）。
抛出：
SAXNotRecognizedException - 如果功能值不能分配或检索。
SAXNotSupportedException - 当 XMLReader 能够识别功能名称但不能设置请求的值时。
另请参见：
getFeature(java.lang.String)

getProperty

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

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

不要求 XMLReaders 能够识别任何特定的属性名称，但要记录 SAX2 的初始核心集。

使用在其自己的 URI 上构建的名称，实现可以随意（并且推荐）设计其自己的属性。

参数：
name - 属性名称，它是一个完全限定 URI。
返回：
属性的当前值。
抛出：
SAXNotRecognizedException - 如果属性值不能分配或检索。
SAXNotSupportedException - 当 XMLReader 能够识别属性名称但此时却不能确定其值时。
另请参见：
setProperty(java.lang.String, java.lang.Object)

setProperty

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

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

不要求 XMLReaders 知道设置任何特定的属性名称，尽管 SAX2 定义了核心集。

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

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

setEntityResolver

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

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

应用程序还可以在解析期间注册新的或不同的解析器，并且 SAX 解析器必须立即开始使用新的解析器。

参数：
resolver - 实体解析器。
另请参见：
getEntityResolver()

getEntityResolver

EntityResolver getEntityResolver()
返回当前的实体解析器。

返回：
当前的实体解析器，如果尚未注册，则返回 null。
另请参见：
setEntityResolver(org.xml.sax.EntityResolver)

setDTDHandler

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

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

应用程序还可以在解析期间注册新的或不同的处理程序，并且 SAX 解析器必须立即开始使用新的处理程序。

参数：
handler - DTD 处理程序。
另请参见：
getDTDHandler()

getDTDHandler

DTDHandler getDTDHandler()
返回当前的 DTD 处理程序。

返回：
当前的 DTD 处理程序，如果尚未注册，则返回 null。
另请参见：
setDTDHandler(org.xml.sax.DTDHandler)

setContentHandler

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

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

应用程序还可以在解析期间注册新的或不同的处理程序，并且 SAX 解析器必须立即开始使用新的处理程序。

参数：
handler - 内容处理程序。
另请参见：
getContentHandler()

getContentHandler

ContentHandler getContentHandler()
返回当前的内容处理程序。

返回：
当前的内容处理程序，如果尚未注册，则返回 null。
另请参见：
setContentHandler(org.xml.sax.ContentHandler)

setErrorHandler

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

如果应用程序不注册错误处理程序，则将默默地忽略由 SAX 解析器报告的所有错误事件；但是不能继续进行常规处理。强烈建议所有的 SAX 应用程序实现错误处理程序，以避免出现不可预料的故障。

应用程序还可以在解析期间注册新的或不同的处理程序，并且 SAX 解析器必须立即开始使用新的处理程序。

参数：
handler - 错误处理程序。
另请参见：
getErrorHandler()

getErrorHandler

ErrorHandler getErrorHandler()
返回当前的错误处理程序。

返回：
当前的错误处理程序，如果尚未注册，则返回 null。
另请参见：
setErrorHandler(org.xml.sax.ErrorHandler)

parse

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

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

在解析正在进行时，应用程序不能调用此方法（它们必须为每个嵌套的 XML 文档创建新的 XMLReader）。一旦完成了解析，应用程序就可以重新使用同一个 XMLReader 对象（可能带有不同的输入源）。在完成解析之前对 XMLReader 对象的配置（例如为功能标记和属性建立的处理程序绑定和值）是不可改变的，除非配置在此方面的定义显式指定了其他行为。（例如，公开被解析的文档的特征的功能标记或属性。）

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

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

参数：
input - XML 文档的顶层的输入源。
抛出：
SAXException - 任何 SAX 异常，可能包装另外的异常。
IOException - 解析器发出的 IO 异常，可能来自应用程序提供的字节流或字符流。
另请参见：
InputSource, parse(java.lang.String), setEntityResolver(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setContentHandler(org.xml.sax.ContentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

parse

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

此方法是从系统标识符读取文档这一常见情形的捷径。它完全等效于以下方法：

 parse(new InputSource(systemId));

如果系统标识符是 URL，则在将它传递到解析器之前必须由应用程序对它进行完整的解析。

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