-
- 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
-
-
字段汇总
-
Fields declared in interface javax.xml.stream.XMLStreamConstants
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
-
-
方法摘要
所有方法 实例方法 抽象方法 变量和类型 方法 描述 void
close()
释放与此Reader相关的任何资源。int
getAttributeCount()
返回此START_ELEMENT上的属性计数,此方法仅在START_ELEMENT或ATTRIBUTE上有效。String
getAttributeLocalName(int index)
返回提供的索引处的属性的localNameQName
getAttributeName(int index)
返回提供的索引处的属性的qnameString
getAttributeNamespace(int index)
返回提供的索引处的属性的名称空间String
getAttributePrefix(int index)
在提供的索引处返回此属性的前缀String
getAttributeType(int index)
返回提供的索引处的属性的XML类型String
getAttributeValue(int index)
返回索引处属性的值String
getAttributeValue(String namespaceURI, String localName)
返回具有namespace和localName的属性的规范化属性值。如果namespaceURI为null,则不检查命名空间的相等性String
getCharacterEncodingScheme()
返回在xml声明中声明的字符编码如果未声明,则返回nullString
getElementText()
读取纯文本元素的内容,如果这不是纯文本元素,则抛出异常。String
getEncoding()
返回输入编码(如果已知)或null(如果未知)int
getEventType()
返回一个整数代码,指示光标指向的事件的类型。String
getLocalName()
返回当前事件的(本地)名称。Location
getLocation()
返回处理器的当前位置。QName
getName()
返回当前START_ELEMENT或END_ELEMENT事件的QNameNamespaceContext
getNamespaceContext()
返回当前位置的只读命名空间上下文。int
getNamespaceCount()
返回在此START_ELEMENT或END_ELEMENT上声明的名称空间的计数,此方法仅在START_ELEMENT,END_ELEMENT或NAMESPACE上有效。String
getNamespacePrefix(int index)
返回在索引处声明的命名空间的前缀。String
getNamespaceURI()
如果当前事件是START_ELEMENT或END_ELEMENT,则此方法返回前缀的URI或默认命名空间。String
getNamespaceURI(int index)
返回索引处声明的命名空间的uri。String
getNamespaceURI(String prefix)
返回给定前缀的uri。String
getPIData()
获取处理指令的数据部分String
getPITarget()
获取处理指令的目标String
getPrefix()
返回当前事件的前缀,如果事件没有前缀,则返回nullObject
getProperty(String name)
从底层实现获取功能/属性的值String
getText()
以字符串形式返回parse事件的当前值,返回CHARACTERS事件的字符串值,返回COMMENT的值,ENTITY_REFERENCE的替换值,CDATA节的字符串值,SPACE的字符串值event,或DTD内部子集的String值。char[]
getTextCharacters()
返回一个包含此事件中字符的数组。int
getTextCharacters(int sourceStart, char[] target, int targetStart, int length)
获取与CHARACTERS,SPACE或CDATA事件关联的文本。int
getTextLength()
返回文本字符数组中此Text事件的字符序列的长度。int
getTextStart()
返回存储第一个字符(此文本事件)的文本字符数组的偏移量。String
getVersion()
获取在xml声明中声明的xml版本如果未声明,则返回nullboolean
hasName()
返回一个布尔值,指示当前事件是否具有名称(是START_ELEMENT还是END_ELEMENT)。boolean
hasNext()
如果有更多解析事件,则返回true;如果没有更多事件,则返回false。boolean
hasText()
返回一个布尔值,指示当前事件是否包含文本。boolean
isAttributeSpecified(int index)
返回一个布尔值,指示默认情况下是否创建了此属性boolean
isCharacters()
如果光标指向字符数据事件,则返回trueboolean
isEndElement()
如果光标指向结束标记,则返回true(否则为false)boolean
isStandalone()
从xml声明中获取独立声明boolean
isStartElement()
如果光标指向开始标记,则返回true(否则为false)boolean
isWhiteSpace()
如果光标指向包含所有空格的字符数据事件,则返回trueint
next()
获取下一个解析事件 - 处理器可以在单个块中返回所有连续的字符数据,或者可以将其拆分为多个块。int
nextTag()
跳过任何空格(isWhiteSpace()返回true),COMMENT或PROCESSING_INSTRUCTION,直到达到START_ELEMENT或END_ELEMENT。void
require(int type, String namespaceURI, String localName)
测试当前事件是否为给定类型,以及命名空间和名称是否与当前事件的当前名称空间和名称匹配。boolean
standaloneSet()
检查文档中是否设置了独立
-
-
-
方法详细信息
-
getProperty
Object getProperty(String name) throws IllegalArgumentException
从底层实现获取功能/属性的值- 参数
-
name
- 属性的名称,不能为null - 结果
- 财产的价值
- 异常
-
IllegalArgumentException
- 如果name为null
-
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; }
- 参数
-
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
-
-