org.codehaus.stax2
Interface XMLStreamReader2

All Superinterfaces:

javax.xml.stream.XMLStreamConstants, javax.xml.stream.XMLStreamReader

All Known Subinterfaces:

StreamReaderImpl

All Known Implementing Classes:

WstxStreamReader

public interface XMLStreamReader2

extends javax.xml.stream.XMLStreamReader

Extended interface that implements functionality that is necessary to properly build event API on top of XMLStreamReader. It also adds limited number of methods that are important for efficient pass-through processing (such as one needed when routing SOAP-messages).

The features supported via setFeature(java.lang.String, java.lang.Object) are:

FEATURE_DTD_OVERRIDE: (write-only)

Feature used to specify the source for DTD external subset to use instead of DTD specified by the XML document itself (if any). Setting the feature for a reader that supports DTD validation essentially allows for injecting an alternate DOCTYPE declaration. Note that setting this value to null is both legal, and sometimes useful: it is equivalent of removing the DOCTYPE declaration.
Feature is write-only, since storing it after loading the DTD in question does not have much use.

Field Summary

static java.lang.String

FEATURE_DTD_OVERRIDE Feature used to specify the source for DTD external subset to use instead of DTD specified by the XML document itself (if any).

Fields inherited from interface javax.xml.stream.XMLStreamConstants

ATTRIBUTE, CDATA, CHARACTERS, COMMENT, DTD, END_DOCUMENT, END_ELEMENT, ENTITY_DECLARATION, ENTITY_REFERENCE, NAMESPACE, NOTATION_DECLARATION, PROCESSING_INSTRUCTION, SPACE, START_DOCUMENT, START_ELEMENT

Method Summary

AttributeInfo	getAttributeInfo() Method that can be called to get additional information about attributes related to the current start element, as well as related DTD-based information if available.
int	getDepth() Method that returns the number of open elements in the stack; 0 when the reader is in prolog/epilog, 1 inside root element and so on.
DTDInfo	getDTDInfo() Method that can be called to get information about DOCTYPE declaration that the reader is currently pointing to, if the reader has parsed it.
java.lang.Object	getFeature(java.lang.String name) Method that can be used to get per-reader values; both generic ones (names for which are defined as constants in this class), and implementation dependant ones.
LocationInfo	getLocationInfo()
int	getText(java.io.Writer w, boolean preserveContents) Method similar to XMLStreamReader.getText(), except that it just uses provided Writer to write all textual content.
boolean	isEmptyElement() Method that can be used to check whether current START_ELEMENT event was created for an empty element (xml short-hand notation where one tag implies start and end, ending with "/>"), or not.
void	setFeature(java.lang.String name, java.lang.Object value) Method that can be used to set per-reader features such as configuration settings; both generic ones (names for which are defined as constants in this class), and implementation dependant ones.
void	skipElement() Method that will skip all the contents of the element that the stream currently points to.

Methods inherited from interface javax.xml.stream.XMLStreamReader

close, getAttributeCount, getAttributeLocalName, getAttributeName, getAttributeNamespace, getAttributePrefix, getAttributeType, getAttributeValue, getAttributeValue, getCharacterEncodingScheme, getElementText, getEncoding, getEventType, getLocalName, getLocation, getName, getNamespaceContext, getNamespaceCount, getNamespacePrefix, getNamespaceURI, getNamespaceURI, getNamespaceURI, getPIData, getPITarget, getPrefix, getProperty, getText, getTextCharacters, getTextCharacters, getTextLength, getTextStart, getVersion, hasName, hasNext, hasText, isAttributeSpecified, isCharacters, isEndElement, isStandalone, isStartElement, isWhiteSpace, next, nextTag, require, standaloneSet

Field Detail

FEATURE_DTD_OVERRIDE

public static final java.lang.String FEATURE_DTD_OVERRIDE

Feature used to specify the source for DTD external subset to use instead of DTD specified by the XML document itself (if any).

See Also:

Constant Field Values

Method Detail

getFeature

public java.lang.Object getFeature(java.lang.String name)

Method that can be used to get per-reader values; both generic ones (names for which are defined as constants in this class), and implementation dependant ones.

Note: although some feature names are shared with setFeature(java.lang.String, java.lang.Object), not all are: some features are read-only, some write-only

Parameters:

name - Name of the feature of which value to get

Returns:

Value of the feature (possibly null), if supported; null otherwise

setFeature

public void setFeature(java.lang.String name,
                       java.lang.Object value)

Method that can be used to set per-reader features such as configuration settings; both generic ones (names for which are defined as constants in this class), and implementation dependant ones.

Note: although some feature names are shared with getFeature(java.lang.String), not all are: some features are read-only, some write-only

Parameters:

name - Name of the feature to set

value - Value to set feature to.

skipElement

public void skipElement()
                 throws javax.xml.stream.XMLStreamException

Method that will skip all the contents of the element that the stream currently points to. Current event when calling the method has to be START_ELEMENT (or otherwise IllegalStateException is thrown); after the call the stream will point to the matching END_ELEMENT event, having skipped zero or more intervening events for the contents.

Throws:

javax.xml.stream.XMLStreamException

getDTDInfo

public DTDInfo getDTDInfo()
                   throws javax.xml.stream.XMLStreamException

Method that can be called to get information about DOCTYPE declaration that the reader is currently pointing to, if the reader has parsed it. Implementations can also choose to return null to indicate they do not provide extra information; but they should not throw any exceptions beyond normal parsing exceptions.

Returns:

Information object for accessing further DOCTYPE information, iff the reader currently points to DTD event, AND is operating in mode that parses such information (DTD-aware at least, and usually also validating)

Throws:

javax.xml.stream.XMLStreamException

getAttributeInfo

public AttributeInfo getAttributeInfo()
                               throws javax.xml.stream.XMLStreamException

Method that can be called to get additional information about attributes related to the current start element, as well as related DTD-based information if available. Note that the reader has to currently point to START_ELEMENT; if not, a IllegalStateException will be thrown.

Throws:

javax.xml.stream.XMLStreamException

getLocationInfo

public LocationInfo getLocationInfo()

getText

public int getText(java.io.Writer w,
                   boolean preserveContents)
            throws java.io.IOException,
                   javax.xml.stream.XMLStreamException

Method similar to XMLStreamReader.getText(), except that it just uses provided Writer to write all textual content. For further optimization, it may also be allowed to do true pass-through, thus possibly avoiding one temporary copy of the data. Finally, note that this method is also guaranteed NOT to return fragments, even when coalescing is not enabled and a parser is otherwised allowed to return partial segments: this requirement is due to there being little benefit in returning such short chunks when streaming. Coalescing property is still honored normally.

Method can only be called on states CDATA, CHARACTERS, COMMENT, DTD, ENTITY_REFERENCE; if called when reader is in another state, IllegalStateException will be thrown. Content written for elements is same as with XMLStreamReader.getText().

Parameters:

w - Writer to use for writing textual contents

preserveContents - If true, reader has to preserve contents so that further calls to getText will return proper conntets. If false, reader is allowed to skip creation of such copies: this can improve performance, but it also means that further calls to getText is not guaranteed to return meaningful data.

Returns:

Number of characters written to the reader

Throws:

java.io.IOException

javax.xml.stream.XMLStreamException

isEmptyElement

public boolean isEmptyElement()
                       throws javax.xml.stream.XMLStreamException

Method that can be used to check whether current START_ELEMENT event was created for an empty element (xml short-hand notation where one tag implies start and end, ending with "/>"), or not.

Note: method may need to read more data to know if the element is an empty one, and as such may throw an i/o or parsing exception (as XMLStreamException); however, it won't throw exceptions for non-START_ELEMENT event types.

Returns:

True, if current event is START_ELEMENT and is based on a parsed empty element; otherwise false

Throws:

javax.xml.stream.XMLStreamException

getDepth

public int getDepth()

Method that returns the number of open elements in the stack; 0 when the reader is in prolog/epilog, 1 inside root element and so on. Depth is same for matching start/end elements, as well as for the immediate non-element children of the element.

Returns:

Number of open elements currently in the reader's stack