-
- 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
- 另请参见:
-
XMLEvent
,XMLInputFactory
,XMLStreamWriter
-
-
Field Summary
-
Fields inherited from 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
-
-
方法摘要
所有方法 接口方法 抽象方法 Modifier and Type 方法 描述 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)
返回具有命名空间和localName的属性的归一化属性值如果namespaceURI为空,则不会检查命名空间是否相等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()
以字符串形式返回解析事件的当前值,返回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版本如果没有声明,则返回nullboolean
hasName()
返回一个布尔值,表示当前事件是否具有名称(是START_ELEMENT或END_ELEMENT)。boolean
hasNext()
如果有更多的解析事件,返回true,如果没有更多的事件,返回false。boolean
hasText()
返回一个布尔值,指示当前事件是否具有文本。boolean
isAttributeSpecified(int index)
返回一个布尔值,表示此属性是否默认创建boolean
isCharacters()
如果光标指向字符数据事件,则返回trueboolean
isEndElement()
如果光标指向结束标记(否则为false),则返回trueboolean
isStandalone()
从xml声明获取独立声明boolean
isStartElement()
如果光标指向起始标记(否则为false),则返回trueboolean
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
- 属性的名称,可能不为空 - 结果
- 物业的价值
- 异常
-
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 - 然后下一个字符部分(另一个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; }
- 参数
-
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
-
-