模块  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（）等方法访问数据。

    使用初始事件类型START_DOCUMENT创建XMLStreamReader实例。 在任何时候，它都有一个当前事件，接口的方法访问并可以通过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
    另请参见：
    XMLEvent ， XMLInputFactory ， XMLStreamWriter

    • 方法详细信息

      • 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-然后是下一个字符部分（另一个字符）
        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为null，则不检查是否相等，如果localName为null，则不检查是否相等。
        参数
        type - 事件类型
        namespaceURI - 事件的uri，可能为null
        localName - 事件的localName，可以为null
        异常
        XMLStreamException - 如果所需值不匹配。

      • getElementText

        String getElementText()
               throws XMLStreamException
        读取纯文本元素的内容，如果这不是纯文本元素，则抛出异常。 无论javax.xml.stream.isCoalescing的值如何，此方法始终返回合并的内容。
        前提条件：当前事件为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'前缀按照Namespaces in XML规范中的定义绑定到“http://www.w3.org/XML/1998/namespace”。

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

        参数
        prefix - 要查找的前缀不能为空
        结果
        uri绑定到给定前缀，如果未绑定，则返回null
        异常
        IllegalArgumentException - 如果前缀为null

      • isStartElement

        boolean isStartElement()
        如果光标指向开始标记，则返回true（否则为false）
        结果
        如果光标指向开始标记，则为true，否则为false

      • isEndElement

        boolean isEndElement()
        如果光标指向结束标记，则返回true（否则为false）
        结果
        如果光标指向结束标记，则为true，否则为false

      • isCharacters

        boolean isCharacters()
        如果光标指向字符数据事件，则返回true
        结果
        如果光标指向字符数据，则返回true，否则返回false

      • isWhiteSpace

        boolean isWhiteSpace()
        如果光标指向包含所有空格的字符数据事件，则返回true
        结果
        如果光标指向所有空格，则返回true，否则返回false

      • getAttributeValue

        String getAttributeValue​(String namespaceURI,
                         String localName)
        返回具有namespace和localName的属性的规范化属性值。如果namespaceURI为null，则不检查命名空间的相等性
        参数
        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（可以为null）
        异常
        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()
        以字符串形式返回parse事件的当前值，返回CHARACTERS事件的字符串值，返回COMMENT的值，ENTITY_REFERENCE的替换值，CDATA节的字符串值，SPACE的字符串值event，或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.如果实际复制的字符数小于“长度”，则不再有文本。 否则，需要进行后续调用，直到检索到所有文本。 例如： 
           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未知，则处理器应返回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()
        检查文档中是否设置了独立
        结果
        如果在文档中设置了standalone，则为true，否则为false

      • getCharacterEncodingScheme

        String getCharacterEncodingScheme()
        返回在xml声明中声明的字符编码如果未声明，则返回null
        结果
        文档中声明的编码或null

      • getPITarget

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

      • getPIData

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