Module  java.xml
软件包  javax.xml.stream

Interface XMLStreamReader

  • All Superinterfaces:
    XMLStreamConstants
    所有已知实现类:
    StreamReaderDelegate


    public interface XMLStreamReader
    extends XMLStreamConstants
    XMLStreamReader接口允许转发,只读访问XML。 它被设计为读取XML数据的最低级别和最有效的方式。

    XMLStreamReader旨在使用next()和hasNext()来迭代XML。 可以使用getEventType(),getNamespaceURI(),getLocalName()和getText()等方法来访问数据;

    创建一个XMLStreamReader实例,其初始事件类型为START_DOCUMENT。 在任何时候,它有一个当前事件接口的方法访问,并可以通过next()方法加载下一个事件。 当前事件类型可以由getEventType()确定,下一个返回的是next()方法。

    解析事件定义为XML声明,DTD,起始标记,字符数据,空格,结束标签,注释或处理指令。 作为查询操作的结果,可能会在文档的根级别遇到属性或命名空间事件。

    对于符合XML 1.0标准,XML处理器必须将声明的未解析实体,符号声明及其相关标识符的标识符传递给应用程序。 此信息通过此接口上的属性API提供。 以下两个属性允许访问此信息:javax.xml.stream.notations和javax.xml.stream.entities。 当当前事件是DTD时,以下调用将返回符号列表List l = (List) getProperty("javax.xml.stream.notations");以下调用将返回实体声明的列表: List l = (List) getProperty("javax.xml.stream.entities");这些属性只能在DTD事件期间被访问,并且如果信息不是,则被定义为返回null可用。

    下表介绍哪些方法在什么状态下有效。 如果一个方法在无效状态中被调用,那么该方法将抛出一个java.lang.IllegalStateException。

    Valid methods for each state Event Type Valid Methods All States getProperty(), hasNext(), require(), close(), getNamespaceURI(), isStartElement(), isEndElement(), isCharacters(), isWhiteSpace(), getNamespaceContext(), getEventType(),getLocation(), hasText(), hasName() START_ELEMENT next(), getName(), getLocalName(), hasName(), getPrefix(), getAttributeXXX(), isAttributeSpecified(), getNamespaceXXX(), getElementText(), nextTag() ATTRIBUTE next(), nextTag() getAttributeXXX(), isAttributeSpecified(), NAMESPACE next(), nextTag() getNamespaceXXX() END_ELEMENT next(), getName(), getLocalName(), hasName(), getPrefix(), getNamespaceXXX(), nextTag() CHARACTERS next(), getTextXXX(), nextTag() CDATA next(), getTextXXX(), nextTag() COMMENT next(), getTextXXX(), nextTag() SPACE next(), getTextXXX(), nextTag() START_DOCUMENT next(), getEncoding(), getVersion(), isStandalone(), standaloneSet(), getCharacterEncodingScheme(), nextTag() END_DOCUMENT close() PROCESSING_INSTRUCTION next(), getPITarget(), getPIData(), nextTag() ENTITY_REFERENCE next(), getLocalName(), getText(), nextTag() DTD next(), getText(), nextTag()
    从以下版本开始:
    1.6
    Version:
    1.0
    另请参见:
    XMLEventXMLInputFactoryXMLStreamWriter
    • 方法详细信息

      • next

        int next​()
          throws XMLStreamException
        获取下一个解析事件 - 处理器可能会在单个块中返回所有连续的字符数据,也可能会将其拆分成多个块。 如果将属性javax.xml.stream.isCoalescing设置为true元素内容必须合并,并且必须为连续的元素内容或CDATA节返回一个CHARACTERS事件。 默认情况下,实体引用必须对应用程序进行扩展和报告。 如果无法扩展实体引用,将抛出异常。 如果元素内容为空(即内容为“”),则不会报告CHARACTERS事件。

        给出以下XML:
        <foo><!--description-->content text<![CDATA[<greeting>Hello>/greeting>]]>other content>/foo>
        在foo上调用next()的行为是:
        1-评论(评论)
        2-然后字符部分(CHARACTERS)
        3然后CDATA部分(另一个字符)
        4 - 然后下一个字符部分(另一个CHARACTERS)
        5,然后END_ELEMENT

        注意:空元素(例如<tag/> )将会报告两个单独的事件:START_ELEMENT,END_ELEMENT - 这将空元素的解析等效保留为<tag></tag> 如果在hasNext()返回false之后调用该方法,则会抛出IllegalStateException异常。

        结果
        对应于当前解析事件的整数代码
        异常
        NoSuchElementException - 如果在hasNext()返回false时调用
        XMLStreamException - 如果处理底层XML源时出错
        另请参见:
        XMLEvent
      • require

        void require​(int type,
                     String namespaceURI,
                     String localName)
              throws XMLStreamException
        测试当前事件是否为给定类型,如果命名空间和名称与当前命名空间和当前事件的名称相匹配。 如果namespaceURI为空,则不检查是否相等,如果localName为空,则不检查其是否相等。
        参数
        type - 事件类型
        namespaceURI - 事件的uri可能为null
        localName - 该事件的localName可以为null
        异常
        XMLStreamException - 如果所需值不匹配。
      • getElementText

        String getElementText​()
                       throws XMLStreamException
        读取纯文本元素的内容,如果这不是纯文本元素,则抛出异常。 不管javax.xml.stream.is的结果如何,这个方法总是返回合并的内容。
        前提条件:当前事件为START_ELEMENT。
        后置条件:当前事件是相应的END_ELEMENT。
        该方法执行以下操作(实现可以自由优化,但必须执行等效处理):
          if(getEventType() != XMLStreamConstants.START_ELEMENT) {
             throw new XMLStreamException(
             "parser must be on START_ELEMENT to read next text", getLocation());
         }
        
         int eventType = next();
         StringBuffer content = new StringBuffer();
         while(eventType != XMLStreamConstants.END_ELEMENT) {
             if(eventType == XMLStreamConstants.CHARACTERS
                || eventType == XMLStreamConstants.CDATA
                || eventType == XMLStreamConstants.SPACE
                || eventType == XMLStreamConstants.ENTITY_REFERENCE) {
                   buf.append(getText());
             } else if(eventType == XMLStreamConstants.PROCESSING_INSTRUCTION
                       || eventType == XMLStreamConstants.COMMENT) {
                 // skipping
             } else if(eventType == XMLStreamConstants.END_DOCUMENT) {
                 throw new XMLStreamException(
                 "unexpected end of document when reading element text content", this);
             } else if(eventType == XMLStreamConstants.START_ELEMENT) {
                 throw new XMLStreamException(
                 "element text content may not contain START_ELEMENT", getLocation());
             } else {
                 throw new XMLStreamException(
                 "Unexpected event type "+eventType, getLocation());
             }
             eventType = next();
         }
         return buf.toString(); 
        异常
        XMLStreamException - 如果当前事件不是START_ELEMENT或遇到非文本元素
      • nextTag

        int nextTag​()
             throws XMLStreamException
        跳过任何空白处(isWhiteSpace()返回true),COMMENT或PROCESSING_INSTRUCTION,直到达到START_ELEMENT或END_ELEMENT。 如果除了空白字符COMMENT,PROCESSING_INSTRUCTION,START_ELEMENT,END_ELEMENT之外,则会抛出异常。 当处理仅由空格分隔的元素内容时,应使用此方法。
        前提条件:无
        后置条件:当前事件为START_ELEMENT或END_ELEMENT,而游标可能已经移动了任何空格事件。
        本质上它执行以下操作(实现可以自由优化,但必须执行等效处理):
           int eventType = next(); while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) // skip whitespace || (eventType == XMLStreamConstants.CDATA && isWhiteSpace()) // skip whitespace || eventType == XMLStreamConstants.SPACE || eventType == XMLStreamConstants.PROCESSING_INSTRUCTION || eventType == XMLStreamConstants.COMMENT ) { eventType = next(); } if (eventType != XMLStreamConstants.START_ELEMENT && eventType != XMLStreamConstants.END_ELEMENT) { throw new String XMLStreamException("expected start or end tag", getLocation()); } return eventType;  
        结果
        读取的元素的事件类型(START_ELEMENT或END_ELEMENT)
        异常
        XMLStreamException - 如果当前事件不是空格,PROCESSING_INSTRUCTION,START_ELEMENT或END_ELEMENT
        NoSuchElementException - 如果在hasNext()返回false时调用
      • hasNext

        boolean hasNext​()
                 throws XMLStreamException
        如果有更多的解析事件,返回true,如果没有更多的事件,返回false。 如果XMLStreamReader的当前状态为END_DOCUMENT,则此方法将返回false
        结果
        如果有更多事件,则为true,否则为false
        异常
        XMLStreamException - 如果检测到下一个状态存在致命错误
      • close

        void close​()
            throws XMLStreamException
        释放与此Reader相关联的任何资源。 此方法不会关闭底层输入源。
        异常
        XMLStreamException - 如果有错误释放相关资源
      • getNamespaceURI

        String getNamespaceURI​(String prefix)
        返回给定前缀的uri。 返回的uri取决于处理器的当前状态。

        注意: “xml”前缀的绑定与“http://www.w3.org/XML/1998/namespace”的Namespaces in XML规范中所定义。

        注意: 'xmlns'前缀必须解析为以下命名空间http://www.w3.org/2000/xmlns/

        参数
        prefix - 查找的前缀可能不为空
        结果
        绑定到给定前缀的uri,如果没有绑定则为null
        异常
        IllegalArgumentException - 如果前缀为空
      • isStartElement

        boolean isStartElement​()
        如果光标指向起始标记(否则为false),则返回true
        结果
        如果光标指向起始标记,则为true,否则为false
      • isEndElement

        boolean isEndElement​()
        如果光标指向结束标记(否则为false),则返回true
        结果
        如果光标指向结束标记,则为true,否则为false
      • isCharacters

        boolean isCharacters​()
        如果光标指向字符数据事件,则返回true
        结果
        如果光标指向字符数据,则为true,否则为false
      • isWhiteSpace

        boolean isWhiteSpace​()
        如果游标指向由所有空格组成的字符数据事件,则返回true
        结果
        如果光标指向所有空格,则为true,否则为false
      • getAttributeValue

        String getAttributeValue​(String namespaceURI,
                                 String localName)
        返回具有命名空间和localName的属性的归一化属性值如果namespaceURI为空,则不会检查命名空间是否相等
        参数
        namespaceURI - 属性的命名空间
        localName - 属性的本地名称,不能为空
        结果
        返回属性的值,如果没有找到则返回null
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributeCount

        int getAttributeCount​()
        返回此START_ELEMENT上的属性数量,此方法仅适用于START_ELEMENT或ATTRIBUTE。 此计数不包括命名空间定义。 属性指数为零。
        结果
        返回属性数
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributeName

        QName getAttributeName​(int index)
        返回提供的索引处的属性的qname
        参数
        index - 属性的位置
        结果
        属性的QName
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributeNamespace

        String getAttributeNamespace​(int index)
        返回在提供的索引处的属性的命名空间
        参数
        index - 属性的位置
        结果
        命名空间URI(可以为空)
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributeLocalName

        String getAttributeLocalName​(int index)
        返回提供的索引处的属性的localName
        参数
        index - 属性的位置
        结果
        该属性的localName
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributePrefix

        String getAttributePrefix​(int index)
        在提供的索引处返回此属性的前缀
        参数
        index - 属性的位置
        结果
        属性的前缀
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributeType

        String getAttributeType​(int index)
        返回提供的索引处的属性的XML类型
        参数
        index - 属性的位置
        结果
        属性的XML类型
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getAttributeValue

        String getAttributeValue​(int index)
        返回索引处的属性值
        参数
        index - 属性的位置
        结果
        属性值
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • isAttributeSpecified

        boolean isAttributeSpecified​(int index)
        返回一个布尔值,表示此属性是否默认创建
        参数
        index - 属性的位置
        结果
        如果这是默认属性,则为true
        异常
        IllegalStateException - 如果这不是START_ELEMENT或ATTRIBUTE
      • getNamespaceCount

        int getNamespaceCount​()
        返回在此START_ELEMENT或END_ELEMENT上声明的命名空间数,此方法仅适用于START_ELEMENT,END_ELEMENT或NAMESPACE。 在END_ELEMENT上,计数是将要超出范围的命名空间。 这相当于SAX回调为终端元素事件报告的信息。
        结果
        返回此特定元素上的命名空间声明的数量
        异常
        IllegalStateException - 如果这不是START_ELEMENT,END_ELEMENT或NAMESPACE
      • getNamespacePrefix

        String getNamespacePrefix​(int index)
        返回在索引处声明的命名空间的前缀。 如果这是默认命名空间声明,则返回null
        参数
        index - 命名空间声明的位置
        结果
        返回命名空间前缀
        异常
        IllegalStateException - 如果这不是START_ELEMENT,END_ELEMENT或NAMESPACE
      • getNamespaceURI

        String getNamespaceURI​(int index)
        返回在索引处声明的命名空间的uri。
        参数
        index - 命名空间声明的位置
        结果
        返回命名空间uri
        异常
        IllegalStateException - 如果这不是START_ELEMENT,END_ELEMENT或NAMESPACE
      • getNamespaceContext

        NamespaceContext getNamespaceContext​()
        返回当前位置的只读命名空间上下文。 上下文是短暂的,只有在对next()的调用才能更改读取器的状态时才有效。
        结果
        返回一个命名空间上下文
      • getEventType

        int getEventType​()
        返回指示光标指向的事件类型的整数代码。 初始事件类型为XMLStreamConstants.START_DOCUMENT
        结果
        当前事件的类型
      • getText

        String getText​()
        以字符串形式返回解析事件的当前值,返回CHARACTERS事件的字符串值,返回COMMENT的值,ENTITY_REFERENCE的替换值,CDATA部分的字符串值,SPACE的字符串值事件或DTD的内部子集的String值。 如果ENTITY_REFERENCE已解决,任何字符数据将被报告为CHARACTERS事件。
        结果
        当前文本或null
        异常
        IllegalStateException - 如果此状态不是有效的文本状态。
      • getTextCharacters

        char[] getTextCharacters​()
        返回一个包含此事件中的字符的数组。 这个数组应该被视为只读和暂时的。 即,数组将包含文本字符,直到XMLStreamReader移动到下一个事件。 尝试在该时间之后保持字符阵列或修改数组的内容是违反该接口的合同。
        结果
        当前文本或空数组
        异常
        IllegalStateException - 如果此状态不是有效的文本状态。
      • getTextCharacters

        int getTextCharacters​(int sourceStart,
                              char[] target,
                              int targetStart,
                              int length)
                       throws XMLStreamException
        获取与CHARACTERS,SPACE或CDATA事件关联的文本。 启动“sourceStart”的文本将从“targetStart”开始复制到“target”中。 最多可以复制“长度”字符。 返回实际复制的字符数。 “sourceStart”参数必须大于或等于0且小于或等于与事件关联的字符数。 通常,一个请求文本从“sourceStart”开始为0.如果实际复制的字符数小于“length”,则不再有文本。 否则,需要进行后续调用,直到检索到所有文本。 例如:
           int length = 1024; char[] myBuffer = new char[ length ]; for ( int sourceStart = 0 ; ; sourceStart += length ) { int nCopied = stream.getTextCharacters( sourceStart, myBuffer, 0, length ); if (nCopied < length) break; }  
        如果基础源中存在任何XML错误,则可能会抛出XMLStreamException。 “targetStart”参数必须大于或等于0且小于“target”的长度,Length必须大于0,“targetStart + length”必须小于或等于“target”的长度。
        参数
        sourceStart - 要复制的源数组中的第一个字符的索引
        target - 目标数组
        targetStart - 目标数组中的起始偏移量
        length - 要复制的字符数
        结果
        实际复制的字符数
        异常
        XMLStreamException - 如果基础XML源格式不正确
        IndexOutOfBoundsException - 如果targetStart <0或>比目标的长度
        IndexOutOfBoundsException - 如果长度<0或targetStart + length>目标长度
        UnsupportedOperationException - 如果不支持此方法
        NullPointerException - 如果target为null
      • getTextStart

        int getTextStart​()
        返回文本字符数组中存在第一个字符(该文本事件)的偏移量。
        结果
        字符数组中文本的起始位置
        异常
        IllegalStateException - 如果此状态不是有效的文本状态。
      • getTextLength

        int getTextLength​()
        返回文本字符数组中此Text事件的字符序列长度。
        结果
        文本的长度
        异常
        IllegalStateException - 如果此状态不是有效的文本状态。
      • getEncoding

        String getEncoding​()
        如果已知返回输入编码,如果未知则返回null。
        结果
        该实例的编码或null
      • hasText

        boolean hasText​()
        返回一个布尔值,指示当前事件是否具有文本。 以下事件具有文本:CHARACTERS,DTD,ENTITY_REFERENCE,COMMENT,SPACE
        结果
        如果事件有文字,则为true,否则为false
      • getLocation

        Location getLocation​()
        返回处理器的当前位置。 如果位置未知,则处理器应返回Location的实现,该位置返回-1的位置,对于publicId和systemId为null。 位置信息仅在调用next()时有效。
        结果
        光标的位置
      • getName

        QName getName​()
        返回当前START_ELEMENT或END_ELEMENT活动的QName
        结果
        当前START_ELEMENT或END_ELEMENT活动的QName
        异常
        IllegalStateException - 如果这不是START_ELEMENT或END_ELEMENT
      • getLocalName

        String getLocalName​()
        返回当前事件的(本地)名称。 START_ELEMENT或END_ELEMENT返回当前元素的(本地)名称。 对于ENTITY_REFERENCE,它返回实体名称。 目前的活动必须是START_ELEMENT或END_ELEMENT,或ENTITY_REFERENCE
        结果
        localName
        异常
        IllegalStateException - 如果这不是START_ELEMENT,END_ELEMENT或ENTITY_REFERENCE
      • hasName

        boolean hasName​()
        返回一个布尔值,表示当前事件是否具有名称(是START_ELEMENT或END_ELEMENT)。
        结果
        如果事件具有名称,则为true,否则为false
      • getNamespaceURI

        String getNamespaceURI​()
        如果当前事件是START_ELEMENT或END_ELEMENT,则此方法返回前缀或缺省命名空间的URI。 如果事件没有前缀,则返回null。
        结果
        绑定到此元素前缀的URI,默认命名空间或null
      • getPrefix

        String getPrefix​()
        返回当前事件的前缀,如果事件没有前缀,则返回null
        结果
        前缀或null
      • getVersion

        String getVersion​()
        获取在xml声明中声明的xml版本如果没有声明,则返回null
        结果
        XML版本或null
      • isStandalone

        boolean isStandalone​()
        从xml声明获取独立声明
        结果
        如果这是独立的,则为true,否则为false
      • standaloneSet

        boolean standaloneSet​()
        检查文档中是否设置了独立的
        结果
        如果在文档中设置了独立,则为true,否则为false
      • getCharacterEncodingScheme

        String getCharacterEncodingScheme​()
        返回在xml声明中声明的字符编码如果没有声明,则返回null
        结果
        在文档中声明的编码或空值
      • getPITarget

        String getPITarget​()
        获取处理指令的目标
        结果
        目标或null
      • getPIData

        String getPIData​()
        获取处理指令的数据部分
        结果
        数据或null