|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
The XMLStreamReader interface allows forward, read-only access to XML. It is designed to be the lowest level and most efficient way to read XML data.
The XMLStreamReader is designed to iterate over XML using next() and hasNext(). The data can be accessed using methods such as getEventType(), getNamespaceURI(), getLocalName() and getText();
The next() method causes the reader to read the next parse event. The next() method returns an integer which identifies the type of event just read.
The event type can be determined using getEventType().
Parsing events are defined as the XML Declaration, a DTD, start tag, character data, white space, end tag, comment, or processing instruction. An attribute or namespace event may be encountered at the root level of a document as the result of a query operation.
For XML 1.0 compliance an XML processor must pass the
identifiers of declared unparsed entities, notation declarations and their
associated identifiers to the application. This information was
provided through the property API on this interface.
The following two properties allowed access to this information:
"javax.xml.stream.notations" and "javax.xml.stream.entities".
These properties are not supported in the JSR 280 subset of StAX;
calls to getProperty("javax.xml.stream.notations");
or getProperty("javax.xml.stream.entities");
will
always return null
.
The following table describes which methods are valid in what state. If a method is called in an invalid state the method will throw a java.lang.IllegalStateException.
Valid methods for each state | |
---|---|
Event Type | Valid Methods |
All States | getProperty(), hasNext(), require(), close(), getNamespaceURI(), isWhiteSpace(), getEventType(),getLocation() |
START_ELEMENT | next(), getLocalName(), getPrefix(), getAttributeXXX(), isAttributeSpecified(), getNamespaceXXX(), getElementText(), nextTag() | ATTRIBUTE | next(), nextTag() getAttributeXXX(), isAttributeSpecified() | NAMESPACE | next(), nextTag() getNamespaceXXX() |
END_ELEMENT | next(), getLocalName(), 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() |
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 |
Method Summary | |
void |
close()
Frees any resources associated with this Reader. |
int |
getAttributeCount()
Returns the count of attributes on this START_ELEMENT, this method is only valid on a START_ELEMENT or ATTRIBUTE. |
String |
getAttributeLocalName(int index)
Returns the localName of the attribute at the provided index |
String |
getAttributeNamespace(int index)
Returns the namespace of the attribute at the provided index |
String |
getAttributePrefix(int index)
Returns the prefix of this attribute at the provided index |
String |
getAttributeType(int index)
Returns the XML type of the attribute at the provided index (see XML 1.0 Specification, section 3.3.1) |
String |
getAttributeValue(int index)
Returns the value of the attribute at the index |
String |
getAttributeValue(String namespaceURI,
String localName)
Returns the normalized attribute value of the attribute with the namespace and localName. |
String |
getCharacterEncodingScheme()
Returns the character encoding declared on the xml declaration Returns null if none was declared |
String |
getElementText()
Reads the content of a text-only element, an exception is thrown if this is not a text-only element. |
String |
getEncoding()
Return input encoding if known or null if unknown. |
int |
getEventType()
Returns an integer code that indicates the type of the event the cursor is pointing to. |
String |
getLocalName()
Returns the (local) name of the current event. |
Location |
getLocation()
Return the current location of the processor. |
int |
getNamespaceCount()
Returns the count of namespaces declared on this START_ELEMENT or END_ELEMENT, this method is only valid on a START_ELEMENT, END_ELEMENT or NAMESPACE. |
String |
getNamespacePrefix(int index)
Returns the prefix for the namespace declared at the index. |
String |
getNamespaceURI()
If the current event is a START_ELEMENT or END_ELEMENT this method returns the URI of the prefix or the default namespace. |
String |
getNamespaceURI(int index)
Returns the uri for the namespace declared at the index. |
String |
getNamespaceURI(String prefix)
Return the uri for the given prefix. |
String |
getPIData()
Get the data section of a processing instruction |
String |
getPITarget()
Get the target of a processing instruction |
String |
getPrefix()
Returns the prefix of the current event or null if the event
does not have a prefix |
Object |
getProperty(String name)
Get the value of a feature/property from the underlying implementation |
String |
getText()
Returns the current value of the parse event as a string, this returns the string value of a CHARACTERS event, returns the value of a COMMENT, the replacement value for an ENTITY_REFERENCE, the string value of a CDATA section, the string value for a SPACE event, or the String value of the internal subset of the DTD. |
char[] |
getTextCharacters()
Returns an array which contains the characters from this event. |
int |
getTextLength()
Returns the length of the sequence of characters for this Text event within the text character array. |
int |
getTextStart()
Returns the offset into the text character array where the first character (of this text event) is stored. |
String |
getVersion()
Get the xml version declared on the xml declaration. |
boolean |
hasNext()
Returns true if there are more parsing events and
false if there are no more events. |
boolean |
isAttributeSpecified(int index)
Returns a boolean which indicates if this attribute was created by default |
boolean |
isStandalone()
Get the standalone declaration from the xml declaration |
boolean |
isWhiteSpace()
Returns true if the cursor points to a character data event
that consists of all whitespace |
int |
next()
Get next parsing event - a processor may return all contiguous character data in a single chunk, or it may split it into several chunks. |
int |
nextTag()
Skips any white space (isWhiteSpace() returns true ), COMMENT,
or PROCESSING_INSTRUCTION,
until a START_ELEMENT or END_ELEMENT is reached. |
void |
require(int type,
String namespaceURI,
String localName)
Test if the current event is of the given type and if the namespace and name match the current namespace and name of the current event. |
boolean |
standaloneSet()
Checks if standalone was set in the document |
Method Detail |
public Object getProperty(String name) throws IllegalArgumentException
name
- The name of the property, may not be null
IllegalArgumentException
- if name is null
public int next() throws XMLStreamException
true
element content must be coalesced and only one CHARACTERS event
must be returned for contiguous element content or
CDATA Sections.
By default entity references must be
expanded and reported transparently to the application.
An exception will be thrown if an entity reference cannot be expanded.
If element content is empty (i.e. content is "") then no CHARACTERS event
will be reported.
Given the following XML:
<foo><!--description-->content text<![CDATA[<greeting>Hello<
/greeting>]]>other content</foo>
The behavior of calling next() when being on foo will be:
1- the comment (COMMENT)
2- then the characters section (CHARACTERS)
3- then the CDATA section (another CHARACTERS)
4- then the next characters section (another CHARACTERS)
5- then the END_ELEMENT
NOTE: empty element (such as <tag/>) will be reported with two separate events: START_ELEMENT, END_ELEMENT - This preserves parsing equivalency of empty element to <tag></tag>.
NoSuchElementException
- if this is called when hasNext() returns
false
XMLStreamException
- if there is an error processing the underlying
XML sourcepublic void require(int type, String namespaceURI, String localName) throws XMLStreamException
null
it is not checked for equality, if the
localName is null
it is not checked for equality.
type
- the event typenamespaceURI
- the uri of the event, may be null
localName
- the localName of the event, may be null
XMLStreamException
- if the required values are not matched.public 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
- if the current event is not a START_ELEMENT
or if a non text element is encounteredpublic int nextTag() throws XMLStreamException
true
), COMMENT,
or PROCESSING_INSTRUCTION,
until a START_ELEMENT or END_ELEMENT is reached.
If other than white space characters, COMMENT, PROCESSING_INSTRUCTION,
START_ELEMENT, END_ELEMENT are encountered, an exception is thrown. This
method should be used when processing element-only content separated by
white space.
int eventType = next(); // skip whitespace while((eventType == XMLStreamConstants.CHARACTERS && isWhiteSpace()) || (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
- if the current event is not white space,
COMMENT, PROCESSING_INSTRUCTION, START_ELEMENT or END_ELEMENT
NoSuchElementException
- if this is called when hasNext() returns
false
public boolean hasNext() throws XMLStreamException
true
if there are more parsing events and
false
if there are no more events. This method will return
false
if the current state of the XMLStreamReader is
END_DOCUMENT
true
if there are more events, false
otherwise
XMLStreamException
- if there is a fatal error detecting the next
statepublic void close() throws XMLStreamException
XMLStreamException
- if there are errors freeing associated resourcespublic String getNamespaceURI(String prefix)
NOTE:The 'xml' prefix is bound as defined in Namespaces in XML specification to "http://www.w3.org/XML/1998/namespace".
NOTE: The 'xmlns' prefix must be resolved to following namespace http://www.w3.org/2000/xmlns/
prefix
- The prefix to lookup, may not be null
null
if it is
not bound
IllegalArgumentException
- if the prefix is null
public boolean isWhiteSpace()
true
if the cursor points to a character data event
that consists of all whitespace
true
if the cursor points to all whitespace,
false
otherwisepublic String getAttributeValue(String namespaceURI, String localName)
null
it is not checked
for equality, i.e. only the localName part of an attribute name will be
compared. A value of ""
(empty String) is interpreted
to mean 'no namespace', i.e. any matching attribute must have no
namespace specified.
namespaceURI
- the namespace of the attributelocalName
- the local name of the attribute, cannot be
null
null
if
not found
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTEpublic int getAttributeCount()
isNamespaceAware
is true; when isNamespaceAware
is false, the attribute
count includes xmlns
and xmlns.*
attributes.
Attribute indices are zero-based.
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTEpublic String getAttributeNamespace(int index)
index
- the position of the attribute
null
)
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTE
IndexOutOfBoundsException
- if the index is invalid or if there is
no attribute at the specified index.public String getAttributeLocalName(int index)
index
- the position of the attribute
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTE
IndexOutOfBoundsException
- if the index is invalid or if there is
no attribute at the specified index.public String getAttributePrefix(int index)
index
- the position of the attribute
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTE
IndexOutOfBoundsException
- if the index is invalid or if there is
no attribute at the specified index.public String getAttributeType(int index)
index
- the position of the attribute
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTE
IndexOutOfBoundsException
- if the index is invalid or if there is
no attribute at the specified index.public String getAttributeValue(int index)
index
- the position of the attribute
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTE
IndexOutOfBoundsException
- if the index is invalid or if there is
no attribute at the specified index.public boolean isAttributeSpecified(int index)
index
- the position of the attribute
true
if this is a default attribute
IllegalStateException
- if this is not a START_ELEMENT or ATTRIBUTEpublic int getNamespaceCount()
IllegalStateException
- if this is not a START_ELEMENT, END_ELEMENT
or NAMESPACEpublic String getNamespacePrefix(int index)
null
if this is the default namespace declaration
index
- the position of the namespace declaration
IllegalStateException
- if this is not a START_ELEMENT, END_ELEMENT
or NAMESPACE
IndexOutOfBoundsException
- if the index is invalid or if there is
no namespace at the specified indexpublic String getNamespaceURI(int index)
index
- the position of the namespace declaration
null
if none exists
IllegalStateException
- if this is not a START_ELEMENT, END_ELEMENT
or NAMESPACEpublic int getEventType()
public String getText()
null
IllegalStateException
- if this state is not
a valid text state.public char[] getTextCharacters()
IllegalStateException
- if this state is not
a valid text state.public int getTextStart()
IllegalStateException
- if this state is not a valid text
state.public int getTextLength()
IllegalStateException
- if this state is not a valid text
state.public String getEncoding()
null
if unknown.
null
.
Note: the source of the encoding is that that may have been provided by
an application to the factory.public Location getLocation()
null
for the
publicId and systemId. The location information is only valid until next()
is called.
public String getLocalName()
IllegalStateException
- if this not a START_ELEMENT,
END_ELEMENT or ENTITY_REFERENCEpublic String getNamespaceURI()
null
if the event does not have a prefix.
null
public String getPrefix()
null
if the event
does not have a prefix
null
public String getVersion()
null
if none was declared.
null
public boolean isStandalone()
true
if this is standalone, or false
otherwisepublic boolean standaloneSet()
true
if standalone was set in the document, or
false
otherwisepublic String getCharacterEncodingScheme()
null
if none was declared
null
public String getPITarget()
null
public String getPIData()
null
|
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |