public interface DTDStreamReader
The DTDStreamReader instance has very specific lifecycle constraints.
An application can only obtain an implementation of DTDStreamReader from
XMLStreamReader
immediately after the method
next()
returns a
DTD
event, and prior to invoking any other
methods on XMLStreamReader
. The
DTDStreamReader instance is obtained by calling method
getProperty
with
"javax.xml.stream.DTDStreamReader"
as the property name
parameter.
Multiple calls to getProperty
with
a "javax.xml.stream.DTDStreamReader"
argument will return the
same instance of DTDStreamReader.
Once the DTDStreamReader object is instantiated by the
application, its various methods can be used to access the DTD data. Its
processing capability extends only until the END_DTD
event
is reached;
at this point, any further document processing must be performed via the
XMLStreamReader
instance.
If an application chooses to instantiate a DTDStreamReader,
the getText()
method on
XMLStreamReader
is invalidated
for the DTD
event: any attempt to invoke
it will generate a java.lang.IllegalStateException
. In this case,
the data for the DTD event must be obtained via the DTDStreamReader
instance.
After DTDStreamReader is instantiated, invocation of any of
the following XMLStreamReader
methods
will change the state of
DTDStreamReader implementation to END_DTD
:
END_DTD
state,
no further processing of the DTD data is possible.
If no instance of DTDStreamReader is created (either the
getProperty
method with parameter
"javax.xml.stream.DTDStreamReader"
is never invoked,
or it returns null
because it is not invoked
immediately after a DTD
event is received),
the behavior of
XMLStreamReader
is unchanged and follows the
specification in
JSR173
for the JSR 280 subset of the API.
DTDStreamReader intentionally mimics
XMLStreamReader
in order to provide developers
with a familiar programming model.
DTDStreamReader includes several methods identical in signature
and semantics to methods defined on XMLStreamReader
.
An object which implements DTDStreamReader uses methods next
and getEventType
to provide the current event type.
The first event is always START_DTD
.
Once an END_DTD
event is returned by methods
next
or getEventType
, the application
must continue further document processing using the
XMLStreamReader
interface.
The application can use the close
method at any time to
terminate processing of any remaining DTD content and skip to the
END_DTD
event.
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. Method next()
is an
exception from this rule: it is defined to throw
NoSuchElementException if it is called when hasNext()
returns false
, so in the case where next()
is called in the END_DTD state it will return NoSuchElementException rather
than java.lang.IllegalStateException.
Valid methods for each state | |
---|---|
Event Type | Valid Methods |
All States | hasNext ,
getEventType ,
getLocation ,
close
|
START_DTD |
next ,
getName ,
getPublicIdentifier ,
getSystemIdentifier
|
END_DTD |
|
ENTITY_DECLARATION |
next ,
getName ,
getPublicIdentifier ,
getSystemIdentifier
getText ,
getTextCharacters ,
getTextStart ,
getTextLength
|
UNPARSED_ENTITY_DECLARATION |
next ,
getName ,
getPublicIdentifier ,
getSystemIdentifier ,
getNotationName
|
NOTATION_DECLARATION |
next ,
getName ,
getPublicIdentifier ,
getSystemIdentifier
|
COMMENT |
next ,
getText ,
getTextCharacters ,
getTextStart ,
getTextLength
|
PROCESSING_INSTRUCTION |
next ,
getPITarget ,
getPIData
|
XMLStreamConstants
,
XMLStreamReader
Modifier and Type | Field and Description |
---|---|
static int |
COMMENT
Indicates an event is a comment.
|
static int |
END_DTD
Indicates an event is the end of a DTD.
|
static int |
ENTITY_DECLARATION
Indicates an event is a parsed entity declaration.
|
static int |
NOTATION_DECLARATION
Indicates an event is a notation declaration.
|
static int |
PROCESSING_INSTRUCTION
Indicates an event is a processing instruction.
|
static int |
START_DTD
Indicates an event is the start of a DTD.
|
static int |
UNPARSED_ENTITY_DECLARATION
Indicates an event is an unparsed entity declaration.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Terminates DTD processing, skipping all DTD related events up
to
END_DTD . |
int |
getEventType()
Returns an integer code that indicates the type of the event at
the current cursor location.
|
Location |
getLocation()
Returns the current location of the processor.
|
java.lang.String |
getName()
Returns the name as a String.
|
java.lang.String |
getNotationName()
Returns the notation name.
|
java.lang.String |
getPIData()
Returns the data section of a processing instruction.
|
java.lang.String |
getPITarget()
Returns the target of a processing instruction.
|
java.lang.String |
getPublicIdentifier()
Returns the public identifier.
|
java.lang.String |
getSystemIdentifier()
Returns the system identifier.
|
java.lang.String |
getText()
Returns the current value of the parse event as a string.
|
char[] |
getTextCharacters()
Returns an array which contains the characters from this event.
|
int |
getTextLength()
Returns the length of the sequence of characters for the current event
within the text character array.
|
int |
getTextStart()
Returns the offset into the text character array at which the first
character of the data for the current event is located.
|
boolean |
hasNext()
Returns
true if there are more parsing events and
false if there are no more events. |
int |
next()
Returns next DTD parsing event.
|
static final int START_DTD
getName
returns the root element's
qualified name, and methods
getPublicIdentifier
and
getSystemIdentifier
return the document's
public and system identifiers.static final int END_DTD
hasNext
returns false
,
and method getEventType
returns
END_DTD
. This event marks the end of the valid
lifecycle of the DTDStreamReader instance, so any
method call other than next
, hasNext
,
getEventType
, close
,
or getLocation
on this interface will
throw java.lang.IllegalStateException.static final int ENTITY_DECLARATION
If
the getTextLength
method returns a negative
value, the event represents an external parsed entity:
method getName
returns the
entity name, methods getPublicIdentifier
and getSystemIdentifier
return the
entity's public and system identifiers, and methods
getText
and getTextCharacters
return null and empty array, respectively.
If the getTextLength
method returns a positive
value, then the event represents an internal parsed entity:
method getName
returns the
entity name, methods getText
or
getTextCharacters
return the replacement
text of an internal parsed entity, and methods
getPublicIdentifier
and
getSystemIdentifier
return null.
static final int UNPARSED_ENTITY_DECLARATION
getName
returns the unparsed
entity name, methods getPublicIdentifier
and getSystemIdentifier
return
the public identifier and the system identifier of an unparsed entity,
and the
method getNotationName
returns the name of
the notation which identifies the format of the unparsed entity.static final int NOTATION_DECLARATION
getName
returns the notation name,
the methods getPublicIdentifier
and getSystemIdentifier
return the
public identifier and the system identifier of the notation.static final int PROCESSING_INSTRUCTION
getPITarget
returns the processing instruction
target and the method getPIData
returns the
processing instruction data section.static final int COMMENT
getText
or
getTextCharacters
return the character
data of the comment, and
the methods getTextStart
and
getTextLength
return the index of the
first character
and the number of characters in the character array returned by
the getTextCharacters
method.int next() throws XMLStreamException
java.util.NoSuchElementException
- if this is called when
hasNext()
returns false
XMLStreamException
- if there is an error processing the
underlying DTD sourceboolean 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 DTDStreamReader is
END_DTD
true
if there are more events, false
otherwiseXMLStreamException
- if there is a fatal error detecting the next
stateint getEventType()
java.lang.String getText()
COMMENT
or the replacement
value for an ENTITY_DECLARATION
. This
method returns null
if there is no text available.null
if there is no text availablejava.lang.IllegalStateException
- if this state is not a valid
text state.char[] getTextCharacters()
java.lang.IllegalStateException
- if this state is not a valid
text state.int getTextStart()
java.lang.IllegalStateException
- if this state is not a valid
text state.int getTextLength()
-1
if there is no text available.-1
java.lang.IllegalStateException
- if this state is not a valid
text state.Location getLocation()
Location
that returns -1
for
each of the lineNumber, columnNumber, and characterOffset,
and null
for each of the publicId and systemId.
The location information is only valid until next()
is called.Location
objectjava.lang.String getPITarget()
null
java.lang.IllegalStateException
- if this method is not valid in
the current state.java.lang.String getPIData()
null
java.lang.IllegalStateException
- if this method is not valid in
the current state.java.lang.String getName()
java.lang.IllegalStateException
- if this state is not a valid
text state.java.lang.String getPublicIdentifier()
java.lang.IllegalStateException
- if this method is not valid in
the current state.java.lang.String getSystemIdentifier()
java.lang.IllegalStateException
- if this method is not valid in
the current state.java.lang.String getNotationName()
java.lang.IllegalStateException
- if this method is not valid in
the current state.void close() throws XMLStreamException
END_DTD
. This method does not close the
underlying input source.
If this method is called when current state is already
END_DTD
, this method does nothing.
Once this method has been invoked,
method hasNext()
returns false
,
method getEventType()
returns
END_DTD
and any other method call except
next()
or getLocation()
on this interface generates an
java.lang.IllegalStateException
.XMLStreamException
- if there is an error processing the
underlying DTD sourceCopyright © 2013, Oracle and/or its affiliates. All rights reserved.
Use is subject to License Terms. Your use of this web site or any of its contents or software indicates your agreement to be bound by these License Terms.