javax.xml.stream
Interface DTDStreamReader

public interface DTDStreamReader

This interface extends the Streaming API for XML (StAX) Cursor API. It enables forward, read-only access to general internal and external parsed and unparsed entity declarations, notation declarations, processing instructions and comments contained in a DTD.

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:

• next(),
• hasNext(),
• nextTag() and
• close().

Once in the 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

Version:

1.0

Author:

Copyright (c) 2006 by BEA Systems. All Rights Reserved.

See Also:

XMLStreamConstants, XMLStreamReader

Field Summary

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.

Method Summary

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.
String	getName() Returns the name as a String.
String	getNotationName() Returns the notation name.
String	getPIData() Returns the data section of a processing instruction.
String	getPITarget() Returns the target of a processing instruction.
String	getPublicIdentifier() Returns the public identifier.
String	getSystemIdentifier() Returns the system identifier.
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.

Field Detail

START_DTD

public static final int START_DTD

Indicates an event is the start of a DTD. On this event, method getName returns the root element's qualified name, and methods getPublicIdentifier and getSystemIdentifier return the document's public and system identifiers.

See Also:

Constant Field Values

END_DTD

public static final int END_DTD

Indicates an event is the end of a DTD. On this event, method 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.

See Also:

Constant Field Values

ENTITY_DECLARATION

public static final int ENTITY_DECLARATION

Indicates an event is a parsed 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.

See Also:

Constant Field Values

UNPARSED_ENTITY_DECLARATION

public static final int UNPARSED_ENTITY_DECLARATION

Indicates an event is an unparsed entity declaration. On this event, method 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.

See Also:

Constant Field Values

NOTATION_DECLARATION

public static final int NOTATION_DECLARATION

Indicates an event is a notation declaration. On this event the method getName returns the notation name, the methods getPublicIdentifier and getSystemIdentifier return the public identifier and the system identifier of the notation.

See Also:

Constant Field Values

PROCESSING_INSTRUCTION

public static final int PROCESSING_INSTRUCTION

Indicates an event is a processing instruction. On this event, the method getPITarget returns the processing instruction target and the method getPIData returns the processing instruction data section.

See Also:

Constant Field Values

COMMENT

public static final int COMMENT

Indicates an event is a comment. On this event, the methods 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.

See Also:

Constant Field Values

Method Detail

next

public int next()
         throws XMLStreamException

Returns next DTD parsing event.

Returns:

the integer code corresponding to the current parse event

Throws:

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

XMLStreamException - if there is an error processing the underlying DTD source

hasNext

public boolean hasNext()
                throws XMLStreamException

Returns 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

Returns:

true if there are more events, false otherwise

Throws:

XMLStreamException - if there is a fatal error detecting the next state

getEventType

public int getEventType()

Returns an integer code that indicates the type of the event at the current cursor location.

Returns:

the integer code corresponding to the current parse event

getText

public String getText()

Returns the current value of the parse event as a string. This returns the value of a COMMENT or the replacement value for an ENTITY_DECLARATION. This method returns null if there is no text available.

Returns:

the current text or null if there is no text available

Throws:

IllegalStateException - if this state is not a valid text state.

getTextCharacters

public char[] getTextCharacters()

Returns an array which contains the characters from this event. This array should be treated as read-only and transient: the array will contain the text characters only until the DTDStreamReader 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.

Returns:

the current text or an empty array

Throws:

IllegalStateException - if this state is not a valid text state.

getTextStart

public int getTextStart()

Returns the offset into the text character array at which the first character of the data for the current event is located.

Returns:

the offset of the first character

Throws:

IllegalStateException - if this state is not a valid text state.

getTextLength

public int getTextLength()

Returns the length of the sequence of characters for the current event within the text character array. This method returns -1 if there is no text available.

Returns:

the length of the character sequence for current event or -1

Throws:

IllegalStateException - if this state is not a valid text state.

getLocation

public Location getLocation()

Returns the current location of the processor. If the location is unknown the processor should return an implementation of 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.

Returns:

the Location object

getPITarget

public String getPITarget()

Returns the target of a processing instruction.

Returns:

the target or null

Throws:

IllegalStateException - if this method is not valid in the current state.

getPIData

public String getPIData()

Returns the data section of a processing instruction.

Returns:

the data or null

Throws:

IllegalStateException - if this method is not valid in the current state.

getName

public String getName()

Returns the name as a String.

Returns:

the name

Throws:

IllegalStateException - if this state is not a valid text state.

getPublicIdentifier

public String getPublicIdentifier()

Returns the public identifier.

Returns:

the public identifier, or null if not available

Throws:

IllegalStateException - if this method is not valid in the current state.

getSystemIdentifier

public String getSystemIdentifier()

Returns the system identifier.

Returns:

the system identifier, or null if not available

Throws:

IllegalStateException - if this method is not valid in the current state.

getNotationName

public String getNotationName()

Returns the notation name.

Returns:

the notation name

Throws:

IllegalStateException - if this method is not valid in the current state.

close

public void close()
           throws XMLStreamException

Terminates DTD processing, skipping all DTD related events up to 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.

Throws:

XMLStreamException - if there is an error processing the underlying DTD source