XMLStreamReader (Java SE 15 & JDK 15) (original) (raw)

All Superinterfaces:

[XMLStreamConstants](XMLStreamConstants.html "interface in javax.xml.stream")

All Known Implementing Classes:

[StreamReaderDelegate](util/StreamReaderDelegate.html "class in javax.xml.stream.util")

public interface XMLStreamReader extends XMLStreamConstants

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();

An XMLStreamReader instance is created with an initial event type START_DOCUMENT. At any moment in time, it has a current event that the methods of the interface access and may load the next event through the next() method. The current event type can be determined by getEventType(), and the next returned by the next() method.

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 is provided through the property API on this interface. The following two properties allow access to this information: javax.xml.stream.notations and javax.xml.stream.entities. When the current event is a DTD the following call will return a list of NotationsList l = (List) getProperty("javax.xml.stream.notations"); The following call will return a list of entity declarations:List l = (List) getProperty("javax.xml.stream.entities"); These properties can only be accessed during a DTD event and are defined to return null if the information is not available.

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(), 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()

Since:

1.6

See Also:

XMLEvent, XMLInputFactory, XMLStreamWriter

Fields declared in interface javax.xml.stream.XMLStreamConstants

[ATTRIBUTE](XMLStreamConstants.html#ATTRIBUTE), [CDATA](XMLStreamConstants.html#CDATA), [CHARACTERS](XMLStreamConstants.html#CHARACTERS), [COMMENT](XMLStreamConstants.html#COMMENT), [DTD](XMLStreamConstants.html#DTD), [END_DOCUMENT](XMLStreamConstants.html#END%5FDOCUMENT), [END_ELEMENT](XMLStreamConstants.html#END%5FELEMENT), [ENTITY_DECLARATION](XMLStreamConstants.html#ENTITY%5FDECLARATION), [ENTITY_REFERENCE](XMLStreamConstants.html#ENTITY%5FREFERENCE), [NAMESPACE](XMLStreamConstants.html#NAMESPACE), [NOTATION_DECLARATION](XMLStreamConstants.html#NOTATION%5FDECLARATION), [PROCESSING_INSTRUCTION](XMLStreamConstants.html#PROCESSING%5FINSTRUCTION), [SPACE](XMLStreamConstants.html#SPACE), [START_DOCUMENT](XMLStreamConstants.html#START%5FDOCUMENT), [START_ELEMENT](XMLStreamConstants.html#START%5FELEMENT)

Modifier and Type Method Description
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
QName getAttributeName​(int index) Returns the qname 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
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 If the namespaceURI is null the namespace is not checked for equality
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.
QName getName() Returns a QName for the current START_ELEMENT or END_ELEMENT event
NamespaceContext getNamespaceContext() Returns a read only namespace context for the current position.
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 getTextCharacters​(int sourceStart, char[] target, int targetStart, int length) Gets the the text associated with a CHARACTERS, SPACE or CDATA 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 Returns null if none was declared
boolean hasName() returns a boolean indicating whether the current event has a name (is a START_ELEMENT or END_ELEMENT).
boolean hasNext() Returns true if there are more parsing events and false if there are no more events.
boolean hasText() Return a boolean indicating whether the current event has text.
boolean isAttributeSpecified​(int index) Returns a boolean which indicates if this attribute was created by default
boolean isCharacters() Returns true if the cursor points to a character data event
boolean isEndElement() Returns true if the cursor points to an end tag (otherwise false)
boolean isStandalone() Get the standalone declaration from the xml declaration
boolean isStartElement() Returns true if the cursor points to a start tag (otherwise false)
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