The Java Community Process(SM) Program - communityprocess

Use of JCP site is subject to the JCP Terms of Use and the Oracle Privacy Policy

DTDStreamReader

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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 its specification in JSR173 .

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.

Valid methods for each state
Event Type	Valid Methods
All States	`hasNext`, `getEventType`, `getLocation`, `close`
`START_DTD`	`next`, `getQualifiedName`, `getPublicIdentifier`, `getSystemIdentifier`
`END_DTD`
`ENTITY_DECLARATION`	`next`, `getQualifiedName`, `getPublicIdentifier`, `getSystemIdentifier` `getText`, `getTextCharacters`, `getTextStart`, `getTextLength`
`UNPARSED_ENTITY_DECLARATION`	`next`, `getQualifiedName`, `getPublicIdentifier`, `getSystemIdentifier`, `getNotationName`
`NOTATION_DECLARATION`	`next`, `getQualifiedName`, `getPublicIdentifier`, `getSystemIdentifier`
`COMMENT`	`next`, `getText`, `getTextCharacters`, `getTextStart`, `getTextLength`
`PROCESSING_INSTRUCTION`	`next`, `getPITarget`, `getPIData`

Version:: 1.1
Author:: Copyright (C) 2006 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`	`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`	`getQualifiedName()` Returns the qualified name.
`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 getQualifiedName 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: 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: 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 getQualifiedName 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 getQualifiedName 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

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 charcter 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 the location 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.

getQualifiedName

public String getQualifiedName()

Returns the qualified name.

Returns:: the qualified 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, or null if not available
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() on this interface generates an java.lang.IllegalStateException.

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