模块  java.xml
软件包  org.xml.sax

Interface XMLReader

  • All Known Subinterfaces:
    XMLFilter
    所有已知实现类:
    ParserAdapterXMLFilterImpl

    public interface XMLReader
    使用回调读取XML文档的接口。
    This module, both source code and documentation, is in the Public Domain, and comes with NO WARRANTY. See http://www.saxproject.org for further information.

    注意:尽管名称如此,但此接口并未扩展标准Java Reader接口,因为读取XML与读取字符数据的操作根本不同。

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

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

    此接口取代了(现已弃用)SAX 1.0 Parser接口。 XMLReader接口包含两个重要的增强功能,而不是旧的Parser接口(以及一些次要的):

    1. 它增加了查询和设置功能和属性的标准方法;
    2. 它添加了Namespace支持,这是许多更高级别XML标准所必需的。

    有适配器可用于将SAX1 Parser转换为SAX2 XMLReader,反之亦然。

    从以下版本开始:
    1.4,SAX 2.0
    另请参见:
    XMLFilterParserAdapterXMLReaderAdapter
    • 方法详细信息

      • 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。
        结果
        功能的当前值(true或false)。
        异常
        SAXNotRecognizedException - 如果无法分配或检索特征值。
        SAXNotSupportedException - 当XMLReader识别功能名称但此时无法确定其值时。
        另请参见:
        setFeature(java.lang.String, boolean)
      • 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识别功能名称但无法设置请求的值时。
        另请参见:
        getFeature(java.lang.String)
      • getProperty

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

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

        虽然为SAX2记录了初始核心集,但XMLReaders不需要识别任何特定的属性名称。

        实现者可以免费(并鼓励)使用基于自己的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可以识别属性名称但无法更改当前值。 某些属性值可能仅在特定上下文中是不可变的或可变的,例如在解析之前,期间或之后。

        虽然核心集由SAX2定义,但XMLReaders不需要识别设置任何特定的属性名称。

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

        参数
        name - 属性名称,它是完全限定的URI。
        value - 属性的请求值。
        异常
        SAXNotRecognizedException - 如果无法分配或检索属性值。
        SAXNotSupportedException - 当XMLReader识别属性名称但无法设置请求的值时。
      • setEntityResolver

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

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

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

        参数
        resolver - 实体解析程序。
        另请参见:
        getEntityResolver()
      • setDTDHandler

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

        如果应用程序未注册DTD处理程序,则将自动忽略SAX解析器报告的所有DTD事件。

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

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

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

        如果应用程序未注册内容处理程序,则将自动忽略SAX解析器报告的所有内容事件。

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

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

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

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

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

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

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

        应用程序可以使用此方法指示XML读取器开始从任何有效的输入源(字符流,字节流或URI)解析XML文档。

        当解析正在进行时,应用程序可能不会调用此方法(它们应该为每个嵌套的XML文档创建一个新的XMLReader)。 解析完成后,应用程序可以重用相同的XMLReader对象,可能使用不同的输入源。 除非配置的该方面的定义明确指定其他行为,否则XMLReader对象的配置(例如为特征标志和属性建立的处理程序绑定和值)将通过完成解析而保持不变。 (例如,要显示正在解析的文档的特征的要素标记或属性。)

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

        此方法是同步的:在解析结束之前它不会返回。 如果客户端应用程序想要提前终止解析,则应该抛出异常。

        参数
        input - XML文档顶级的输入源。
        异常
        SAXException - 任何SAX异常,可能包含另一个异常。
        IOException - 解析器的IO异常,可能来自应用程序提供的字节流或字符流。
        另请参见:
        InputSourceparse(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,则在将其传递给解析器之前,应用程序必须完全解析该URL。

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