This method works similarly to next() but will expose additional event types (COMMENT, CDSECT, DOCDECL,
ENTITY_REF, PROCESSING_INSTRUCTION, or IGNORABLE_WHITESPACE) if they are available in input.
If special feature FEATURE_XML_ROUNDTRIP
(identified by URI: http://xmlpull.org/v1/doc/features.html#xml-roundtrip) is enabled it is possible to do XML
document round trip ie. reproduce exactly on output the XML input using getText(): returned content is always
unnormalized (exactly as in input). Otherwise returned content is end-of-line normalized as described
XML 1.0 End-of-Line Handling and. Also when this feature
is enabled exact content of START_TAG, END_TAG, DOCDECL and PROCESSING_INSTRUCTION is available.
Here is the list of tokens that can be returned from nextToken() and what getText() and getTextCharacters()
returns:
START_DOCUMENT
null
END_DOCUMENT
null
START_TAG
null unless FEATURE_XML_ROUNDTRIP enabled and then returns XML tag, ex: <tag attr='val'>
END_TAG
null unless FEATURE_XML_ROUNDTRIP id enabled and then returns XML tag, ex: </tag>
TEXT
return element content.
Note: that element content may be delivered in multiple consecutive TEXT events.
IGNORABLE_WHITESPACE
return characters that are determined to be ignorable white space. If the FEATURE_XML_ROUNDTRIP is enabled
all whitespace content outside root element will always reported as IGNORABLE_WHITESPACE otherwise reporting is
optional.
Note: that element content may be delivered in multiple consecutive IGNORABLE_WHITESPACE events.
CDSECT
return text inside CDATA (ex. 'fo<o' from <!CDATA[fo<o]]>)
PROCESSING_INSTRUCTION
if FEATURE_XML_ROUNDTRIP is true return exact PI content ex: 'pi foo' from <?pi foo?> otherwise it may be
exact PI content or concatenation of PI target, space and data so for example for <?target data?> string
"target data" may be returned if FEATURE_XML_ROUNDTRIP is false.
COMMENT
return comment content ex. 'foo bar' from <!--foo bar-->
ENTITY_REF
getText() MUST return entity replacement text if PROCESS_DOCDECL is false otherwise getText() MAY return
null, additionally getTextCharacters() MUST return entity name (for example 'entity_name' for &entity_name;).
NOTE: this is the only place where value returned from getText() and getTextCharacters() are
different
NOTE: it is user responsibility to resolve entity reference if PROCESS_DOCDECL is false and there is no
entity replacement text set in defineEntityReplacementText() method (getText() will be null)
NOTE: character entities (ex.  ) and standard entities such as & < >
" ' are reported as well and are not reported as TEXT tokens but as ENTITY_REF tokens!
This requirement is added to allow to do roundtrip of XML documents!
DOCDECL
if FEATURE_XML_ROUNDTRIP is true or PROCESS_DOCDECL is false then return what is inside of DOCDECL for
example it returns:
" titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
[<!ENTITY % active.links "INCLUDE">]"
for input document that contained:
<!DOCTYPE titlepage SYSTEM "http://www.foo.bar/dtds/typo.dtd"
[<!ENTITY % active.links "INCLUDE">]>
otherwise if FEATURE_XML_ROUNDTRIP is false and PROCESS_DOCDECL is true then what is returned is undefined (it
may be even null)
NOTE: there is no guarantee that there will only one TEXT or IGNORABLE_WHITESPACE event from
nextToken() as parser may chose to deliver element content in multiple tokens (dividing element content into
chunks)
NOTE: whether returned text of token is end-of-line normalized is depending on
FEATURE_XML_ROUNDTRIP.
NOTE: XMLDecl (<?xml ...?>) is not reported but its content is available through optional
properties (see class description above).