public interface XMLStreamReader
XMLStreamReader 接口允许转发 XML 和对 XML 的只读访问。它被设计为读取 XML 数据的最低层且最有效的方法。
XMLStreamReader 被设计为使用 next() 和 hasNext() 在 XML 上进行迭代。可以使用诸如 getEventType()、getNamespaceURI()、getLocalName() 和 getText() 之类的方法访问数据:
next() 方法会使 reader 读取下一个解析事件。next() 方法返回一个整数,指示刚才读取的事件类型。
事件类型可以使用 getEventType() 来确定。
解析事件被定义为 XML 声明、DTD、开始标记、字符数据、空格、结束标记、注释或处理指令。属性或名称空间事件可以作为查询操作的结果在文档的根级别出现。
为了遵守 XML 1.0,XML 处理器必须将已声明的未解析实体的标识符、注释声明及其关联标识符传递给应用程序。此信息通过此接口上的属性 API 提供。以下两个属性允许访问此信息:javax.xml.stream.notations 和 javax.xml.stream.entities。当前事件为 DTD 时,以下调用将返回一个 Notation 列表 List l = (List) getProperty("javax.xml.stream.notations");
以下调用将返回一个实体声明列表:List l = (List) getProperty("javax.xml.stream.entities");
这些属性只能在 DTD 事件中访问,并且被定义为如果信息不可用,则返回 null。
下表描述了各种状态所对应的有效方法。如果某种方法是在无效状态中调用的,则该方法将抛出 java.lang.IllegalStateException。
每种状态对应的有效方法 | |
---|---|
事件类型 | 有效方法 |
所有状态 | 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
字段摘要 |
---|
从接口 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) 返回所提供索引处的属性的 localName |
QName |
getAttributeName(int index) 返回所提供索引处的属性的 qname |
String |
getAttributeNamespace(int index) 返回所提供索引处的属性的名称空间 |
String |
getAttributePrefix(int index) 返回所提供索引处的属性的前缀 |
String |
getAttributeType(int index) 返回所提供索引处的属性的 XML 类型 |
String |
getAttributeValue(int index) 返回 index 处的属性值 |
String |
getAttributeValue(String namespaceURI, String localName) 返回带有名称空间和 localName 的属性的规范化属性值。 |
String |
getCharacterEncodingScheme() 返回 xml 声明中声明的字符编码。 |
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) 返回在 index 处声明的名称空间前缀。 |
String |
getNamespaceURI() 如果当前事件是 START_ELEMENT 或 END_ELEMENT,则此方法返回前缀的 URI 或默认名称空间。 |
String |
getNamespaceURI(int index) 返回在 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 内部子集的字符串值。 |
char[] |
getTextCharacters() 返回一个包含此事件中字符的数组。 |
int |
getTextCharacters(int sourceStart, char[] target, int targetStart, int length) 获取与 CHARACTERS、SPACE 或 CDATA 事件关联的文本。 |
int |
getTextLength() 返回文本字符数组中此文本事件的字符序列长度。 |
int |
getTextStart() 返回存储(此文本事件的)第一个字符位置处的文本字符数组的偏移量。 |
String |
getVersion() 获取在 xml 声明中声明的 xml 版本,如果没有声明版本,则返回 null |
boolean |
hasName() 如果当前事件有名称(是 START_ELEMENT 或 END_ELEMENT),则返回 ture,否则返回 false |
boolean |
hasNext() 如果有多个解析事件,则返回 true,如果不再有事件,则返回 false。 |
boolean |
hasText() 如果当前事件具有文本,则返回 true,否则返回 false。 |
boolean |
isAttributeSpecified(int index) 返回一个 boolean 值,它指示此属性是否为默认创建的 |
boolean |
isCharacters() 如果光标指向字符数据事件,则返回 true |
boolean |
isEndElement() 如果光标指向结束标记,则返回 true(否则返回 false) |
boolean |
isStandalone() 获取 xml 声明中的独立声明 |
boolean |
isStartElement() 如果光标指向开始标记,则返回 true(否则返回 false) |
boolean |
isWhiteSpace() 如果光标指向由所有空格组成的字符数据事件,则返回 true |
int |
next() 获取下一个解析事件??处理器可以用单个存储块返回所有连续的字符数据,它也可以将其分割成几个存储块。 |
int |
nextTag() 在到达 START_ELEMENT 或 END_ELEMENT 之前,跳过所有空格(isWhiteSpace() 返回 true)、COMMENT 或 PROCESSING_INSTRUCTION。 |
void |
require(int type, String namespaceURI, String localName) 测试当前事件是否属于给定的类型,以及名称空间和名称是否与当前事件的当前名称空间和名称相匹配。 |
boolean |
standaloneSet() 检查文档中是否设置了独立 |
方法详细信息 |
---|
Object getProperty(String name) throws IllegalArgumentException
name
- 属性的名称,不可以为 null
IllegalArgumentException
- 如果名称为 null
int next() throws XMLStreamException
假设给定以下 XML:
<foo><!--description-->内容文本<![CDATA[<greeting>Hello</greeting>]]>其他内容</foo>
对 foo 调用 next() 的行为将是:
1- 注释 (COMMENT)
2- 然后是字符节 (CHARACTERS)
3- 接下来是 CDATA 节(另一个 CHARACTERS)
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)
注:根据 Namespaces in XML 规范中的定义,'xml' 前缀被绑定到 "http://www.w3.org/XML/1998/namespace"。
注:'xmlns' 前缀必须被解析到以下名称空间:http://www.w3.org/2000/xmlns/
prefix
- 要查找的前缀,不可以为 null
IllegalArgumentException
- 如果前缀为 null
boolean isStartElement()
boolean isEndElement()
boolean isCharacters()
boolean isWhiteSpace()
String getAttributeValue(String namespaceURI, String localName)
namespaceURI
- 属性的名称空间
localName
- 属性的本地名称,不可以为 null
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
int getAttributeCount()
IllegalStateException
- 如果这不是 START_ELEMENT 或 ATTRIBUTE
QName getAttributeName(int index)
index
- 属性的位置
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
String getAttributeNamespace(int index)
index
- 属性的位置
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
String getAttributeLocalName(int index)
index
- 属性的位置
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
String getAttributePrefix(int index)
index
- 属性的位置
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
String getAttributeType(int index)
index
- 属性的位置
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
String getAttributeValue(int index)
index
- 属性的位置
IllegalStateException
- 如果不是 START_ELEMENT 或 ATTRIBUTE
boolean isAttributeSpecified(int 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
- 如果 length < 0 或 targetStart + length > 目标长度
UnsupportedOperationException
- 如果此方法不受支持
NullPointerException
- 如果目标为 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