public interface XMLStreamReader extends XMLStreamConstants
XMLStreamReader旨在使用next()和hasNext()来迭代XML。 可以使用getEventType(),getNamespaceURI(),getLocalName()和getText()等方法来访问数据;
next()方法使读者阅读下一个解析事件。 next()方法返回一个整数,它标识刚刚读取的事件的类型。
事件类型可以使用getEventType()确定 。
解析事件定义为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()XMLEvent
, XMLInputFactory
, XMLStreamWriter
ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT
Modifier and Type | Method and Description |
---|---|
void |
close()
释放与此Reader相关联的任何资源。
|
int |
getAttributeCount()
返回此START_ELEMENT上的属性数量,此方法仅适用于START_ELEMENT或ATTRIBUTE。
|
String |
getAttributeLocalName(int index)
返回提供的索引处的属性的localName
|
QName |
getAttributeName(int index)
返回提供的索引处的属性的qname
|
String |
getAttributeNamespace(int index)
返回在提供的索引处的属性的命名空间
|
String |
getAttributePrefix(int index)
在提供的索引处返回此属性的前缀
|
String |
getAttributeType(int index)
返回提供的索引处的属性的XML类型
|
String |
getAttributeValue(int index)
返回索引处的属性值
|
String |
getAttributeValue(String namespaceURI, String localName)
返回具有命名空间和localName的属性的归一化属性值如果namespaceURI为空,则不会检查命名空间是否相等
|
String |
getCharacterEncodingScheme()
返回在xml声明中声明的字符编码如果没有声明,则返回null
|
String |
getElementText()
读取纯文本元素的内容,如果这不是纯文本元素,则抛出异常。
|
String |
getEncoding()
如果已知返回输入编码,如果未知则返回null。
|
int |
getEventType()
返回指示光标指向的事件类型的整数代码。
|
String |
getLocalName()
返回当前事件的(本地)名称。
|
Location |
getLocation()
返回处理器的当前位置。
|
QName |
getName()
返回当前START_ELEMENT或END_ELEMENT活动的QName
|
NamespaceContext |
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()
返回当前事件的前缀,如果事件没有前缀,则返回null
|
Object |
getProperty(String name)
从底层实现获取特征/属性的值
|
String |
getText()
以字符串形式返回解析事件的当前值,返回CHARACTERS事件的字符串值,返回COMMENT的值,ENTITY_REFERENCE的替换值,CDATA部分的字符串值,SPACE的字符串值事件或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版本如果没有声明,则返回null
|
boolean |
hasName()
如果当前事件有一个名称(是START_ELEMENT或END_ELEMENT)返回false则返回true
|
boolean |
hasNext()
如果有更多的解析事件,返回true,如果没有更多的事件,返回false。
|
boolean |
hasText()
如果当前事件有文本,则返回true,否则返回false以下事件具有文本:CHARACTERS,DTD,ENTITY_REFERENCE,COMMENT,SPACE
|
boolean |
isAttributeSpecified(int index)
返回一个布尔值,表示此属性是否默认创建
|
boolean |
isCharacters()
如果光标指向字符数据事件,则返回true
|
boolean |
isEndElement()
如果光标指向结束标记(否则为false),则返回true
|
boolean |
isStandalone()
从xml声明获取独立声明
|
boolean |
isStartElement()
如果光标指向起始标记(否则为false),则返回true
|
boolean |
isWhiteSpace()
如果游标指向由所有空格组成的字符数据事件,则返回true
|
int |
next()
获取下一个解析事件 - 处理器可能会在单个块中返回所有连续的字符数据,也可能会将其拆分成多个块。
|
int |
nextTag()
跳过任何空白处(isWhiteSpace()返回true),COMMENT或PROCESSING_INSTRUCTION,直到达到START_ELEMENT或END_ELEMENT。
|
void |
require(int type, String namespaceURI, String localName)
测试当前事件是否为给定类型,如果命名空间和名称与当前命名空间和当前事件的名称相匹配。
|
boolean |
standaloneSet()
检查文档中是否设置了独立的
|
Object getProperty(String name) throws IllegalArgumentException
name
- 属性的名称,可能不为空
IllegalArgumentException
- 如果name为null
int next() throws XMLStreamException
给出以下XML:
<foo> <! - description - >内容文本<![CDATA [<greeting> Hello </ greeting>]]>其他内容</ 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
void require(int type, String namespaceURI, String localName) throws XMLStreamException
type
- 事件类型
namespaceURI
- 事件的uri可能为null
localName
- 该事件的localName可能为null
XMLStreamException
- 如果所需值不匹配。
String getElementText() throws XMLStreamException
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或遇到非文本元素
int nextTag() throws XMLStreamException
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;
XMLStreamException
- 如果当前事件不是空格,PROCESSING_INSTRUCTION,START_ELEMENT或END_ELEMENT
NoSuchElementException
- 如果在hasNext()返回false时调用
boolean hasNext() throws XMLStreamException
XMLStreamException
- 如果检测到下一个状态存在致命错误
void close() throws XMLStreamException
XMLStreamException
- 如果有错误释放相关资源
String getNamespaceURI(String prefix)
注意: “xml”前缀的绑定方式与“http://www.w3.org/XML/1998/namespace”的Namespaces in XML规范中定义。
注意: 'xmlns'前缀必须解析为以下命名空间http://www.w3.org/2000/xmlns/
prefix
- 查找的前缀可能不为空
IllegalArgumentException
- 如果前缀为空
boolean isStartElement()
boolean isEndElement()
boolean isCharacters()
boolean isWhiteSpace()
String getAttributeValue(String namespaceURI, String localName)
namespaceURI
- 属性的命名空间
localName
-
localName
的本地名称,不能为空
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
int getAttributeCount()
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
QName getAttributeName(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
String getAttributeNamespace(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
String getAttributeLocalName(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
String getAttributePrefix(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
String getAttributeType(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
String getAttributeValue(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
boolean isAttributeSpecified(int index)
index
-
index
的位置
IllegalStateException
- 如果这不是START_ELEMENT或ATTRIBUTE
int getNamespaceCount()
IllegalStateException
- 如果这不是START_ELEMENT,END_ELEMENT或NAMESPACE
String getNamespacePrefix(int index)
index
- 命名空间声明的位置
IllegalStateException
- 如果这不是START_ELEMENT,END_ELEMENT或NAMESPACE
String getNamespaceURI(int index)
index
- 命名空间声明的位置
IllegalStateException
- 如果这不是START_ELEMENT,END_ELEMENT或NAMESPACE
NamespaceContext getNamespaceContext()
int getEventType()
String getText()
IllegalStateException
- 如果此状态不是有效的文本状态。
char[] getTextCharacters()
IllegalStateException
- 如果此状态不是有效的文本状态。
int getTextCharacters(int sourceStart, char[] target, int targetStart, int length) throws XMLStreamException
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
int getTextStart()
IllegalStateException
- 如果此状态不是有效的文本状态。
int getTextLength()
IllegalStateException
- 如果此状态不是有效的文本状态。
String getEncoding()
boolean hasText()
Location getLocation()
QName getName()
IllegalStateException
- 如果这不是START_ELEMENT或END_ELEMENT
String getLocalName()
IllegalStateException
- 如果这不是START_ELEMENT,END_ELEMENT或ENTITY_REFERENCE
boolean hasName()
String getNamespaceURI()
String getPrefix()
String getVersion()
boolean isStandalone()
boolean standaloneSet()
String getCharacterEncodingScheme()
String getPITarget()
String getPIData()