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 Notations
List 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.

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

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.

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.
If the property javax.xml.stream.isCoalescing is set to 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>.
This method will throw an IllegalStateException if it is called after hasNext() returns false.

Returns:

the integer code corresponding to the current parse event

Throws:

NoSuchElementException - if this is called when hasNext() returns false

require

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. If the namespaceURI is null it is not checked for equality,
if the localName is null it is not checked for equality.

getElementText

Reads the content of a text-only element, an exception is thrown if this is
not a text-only element.
Regardless of value of javax.xml.stream.isCoalescing this method always returns coalesced content.
Precondition: the current event is START_ELEMENT.
Postcondition: the current event is the corresponding END_ELEMENT.
The method does the following (implementations are free to optimized
but must do equivalent processing):

nextTag

Skips any white space (isWhiteSpace() returns 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 seperated by white space.
Precondition: none
Postcondition: the current event is START_ELEMENT or END_ELEMENT
and cursor may have moved over any whitespace event.
Essentially it does the following (implementations are free to optimized
but must do equivalent processing):

getNamespaceCount

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. On
an END_ELEMENT the count is of the namespaces that are about to go
out of scope. This is the equivalent of the information reported
by SAX callback for an end element event.

getEventType

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.
If an ENTITY_REFERENCE has been resolved, any character data
will be reported as CHARACTERS events.

getTextCharacters

char[] getTextCharacters()

Returns an array which contains the characters from this event.
This array should be treated as read-only and transient. I.e. the array will
contain the text characters until the XMLStreamReader moves on to the next event.
Attempts to hold onto the character array beyond that time or modify the
contents of the array are breaches of the contract for this interface.

getTextCharacters

Gets the the text associated with a CHARACTERS, SPACE or CDATA event.
Text starting a "sourceStart" is copied into "target" starting at "targetStart".
Up to "length" characters are copied. The number of characters actually copied is returned.
The "sourceStart" argument must be greater or equal to 0 and less than or equal to
the number of characters associated with the event. Usually, one requests text starting at a "sourceStart" of 0.
If the number of characters actually copied is less than the "length", then there is no more text.
Otherwise, subsequent calls need to be made until all text has been retrieved. For example:
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;
}
XMLStreamException may be thrown if there are any XML errors in the underlying source.
The "targetStart" argument must be greater than or equal to 0 and less than the length of "target",
Length must be greater than 0 and "targetStart + length" must be less than or equal to length of "target".

Parameters:

sourceStart - the index of the first character in the source array to copy

hasText

getLocation

Return the current location of the processor.
If the Location is unknown the processor should return
an implementation of Location that returns -1 for the
location and null for the publicId and systemId.
The location information is only valid until next() is
called.

getLocalName

Returns the (local) name of the current event.
For START_ELEMENT or END_ELEMENT returns the (local) name of the current element.
For ENTITY_REFERENCE it returns entity name.
The current event must be START_ELEMENT or END_ELEMENT,
or ENTITY_REFERENCE