DTDStreamReader (JOSH API Document)

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:

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`

See Also:: XMLStreamConstants, XMLStreamReader

Field Summary

Fields
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.

Method Summary

Methods
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.
`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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
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
```
String getName()
```
    Returns the name as a String.
    
    Returns:
    the name
    
    Throws:
    
    IllegalStateException - if this state is not a valid text state.
  - getPublicIdentifier
```
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
```
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
```
String getNotationName()
```
    Returns the notation name.
    
    Returns:
    the notation name
    
    Throws:
    
    IllegalStateException - if this method is not valid in the current state.
  - close
```
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

Interface DTDStreamReader

Field Summary

Method Summary

Field Detail

START_DTD

END_DTD

ENTITY_DECLARATION

UNPARSED_ENTITY_DECLARATION

NOTATION_DECLARATION

PROCESSING_INSTRUCTION

COMMENT

Method Detail

next

hasNext

getEventType

getText

getTextCharacters

getTextStart

getTextLength

getLocation

getPITarget

getPIData

getName

getPublicIdentifier

getSystemIdentifier

getNotationName

close