org.codehaus.stax2
Interface XMLStreamReader2

All Superinterfaces:
TypedXMLStreamReader, Validatable, javax.xml.stream.XMLStreamConstants, javax.xml.stream.XMLStreamReader
All Known Implementing Classes:
DOMWrappingReader, Stax2FilteredStreamReader, Stax2ReaderAdapter, Stax2ReaderImpl, StreamReader2Delegate

public interface XMLStreamReader2
extends TypedXMLStreamReader, Validatable

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.

Since version 3.0, stream writer will also implement "Typed Access API" on output side.

Version:
3.0.1 06-Nov-2008
Author:
Tatu Saloranta ([email protected])

Field Summary
static String FEATURE_DTD_OVERRIDE
          Deprecated. Use XMLInputFactory2.P_DTD_OVERRIDE instead.
 
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
 void closeCompletely()
          Method similar to XMLStreamReader.getNamespaceContext(), except that this method also does close the underlying input source if it has not yet been closed.
 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 (including when pointing at the root element itself) 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.
 Object getFeature(String name)
          Deprecated. Should use XMLStreamReader.getProperty(java.lang.String) instead
 LocationInfo getLocationInfo()
           
 NamespaceContext getNonTransientNamespaceContext()
          This method returns a namespace context object that contains information identical to that returned by XMLStreamReader.getNamespaceContext(), but one that is not transient.
 String getPrefixedName()
          This method returns "prefix-qualified" name of the current element.
 int getText(Writer w, boolean preserveContents)
          Method similar to XMLStreamReader.getText(), except that it just uses provided Writer to write all textual content, and that it works for wider range of event types.
 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.
 boolean isPropertySupported(String name)
          Method similar to XMLInputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Reader instance.
 void setFeature(String name, Object value)
          Deprecated. Should use setProperty(java.lang.String, java.lang.Object) instead
 boolean setProperty(String name, Object value)
          Method that can be used to set per-reader properties; a subset of properties one can set via matching XMLInputFactory2 instance.
 void skipElement()
          Method that will skip all the contents of the element that the stream currently points to.
 
Methods inherited from interface org.codehaus.stax2.typed.TypedXMLStreamReader
getAttributeAs, getAttributeAsArray, getAttributeAsBinary, getAttributeAsBinary, getAttributeAsBoolean, getAttributeAsDecimal, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsFloat, getAttributeAsFloatArray, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsInteger, getAttributeAsLong, getAttributeAsLongArray, getAttributeAsQName, getAttributeIndex, getElementAs, getElementAsBinary, getElementAsBinary, getElementAsBoolean, getElementAsDecimal, getElementAsDouble, getElementAsFloat, getElementAsInt, getElementAsInteger, getElementAsLong, getElementAsQName, readElementAsArray, readElementAsBinary, readElementAsBinary, readElementAsDoubleArray, readElementAsFloatArray, readElementAsIntArray, readElementAsLongArray
 
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
 
Methods inherited from interface org.codehaus.stax2.validation.Validatable
setValidationProblemHandler, stopValidatingAgainst, stopValidatingAgainst, validateAgainst
 

Field Detail

FEATURE_DTD_OVERRIDE

static final String FEATURE_DTD_OVERRIDE
Deprecated. Use XMLInputFactory2.P_DTD_OVERRIDE instead.
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

isPropertySupported

boolean isPropertySupported(String name)
Method similar to XMLInputFactory.isPropertySupported(java.lang.String), used to determine whether a property is supported by the Reader instance. This means that this method may return false for some properties that the input factory does support: specifically, it should only return true if the value is mutable on per-instance basis. False means that either the property is not recognized, or is not mutable via reader instance.


setProperty

boolean setProperty(String name,
                    Object value)
Method that can be used to set per-reader properties; a subset of properties one can set via matching XMLInputFactory2 instance. Exactly which methods are mutable is implementation specific.

Parameters:
name - Name of the property to set
value - Value to set property to.
Returns:
True, if the specified property was succesfully set to specified value; false if its value was not changed
Throws:
InvalidArgumentException - if the property is not supported (or recognized) by the stream reader implementation

getFeature

Object getFeature(String name)
Deprecated. Should use XMLStreamReader.getProperty(java.lang.String) instead

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

void setFeature(String name,
                Object value)
Deprecated. Should use setProperty(java.lang.String, java.lang.Object) instead

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

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

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

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

LocationInfo getLocationInfo()

getText

int getText(Writer w,
            boolean preserveContents)
            throws IOException,
                   javax.xml.stream.XMLStreamException
Method similar to XMLStreamReader.getText(), except that it just uses provided Writer to write all textual content, and that it works for wider range of event types. 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, SPACE and PROCESSING_INSTRUCTION; 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:
IOException
javax.xml.stream.XMLStreamException

isEmptyElement

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

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 (including when pointing at the root element itself) and so on. Depth is same for matching start/end elements, as well as for the all children of an element.

Returns:
Number of open elements currently in the reader's stack, including current START_ELEMENT or END_ELEMENT (if pointing to one).

getNonTransientNamespaceContext

NamespaceContext getNonTransientNamespaceContext()
This method returns a namespace context object that contains information identical to that returned by XMLStreamReader.getNamespaceContext(), but one that is not transient. That is, one that will remain valid and unchanged after its creation. This allows the namespace context to be used independent of its source documents life cycle. One possible use case is to use this namespace context for 'initializing' writers (especially ones that use repairing mode) with optimal/preferred name space bindings.

Returns:
Non-transient namespace context as explained above.

getPrefixedName

String getPrefixedName()
This method returns "prefix-qualified" name of the current element. In general, this means character-by-character exact name of the element in XML content, and may be useful in informational purposes, as well as when interacting with packages and APIs that use such names (such as what SAX may use as qnames).

Note: implementations are encouraged to provide an implementation that would be more efficient than calling getLocalName and getPrefix separately, but are not required to do so. Nonetheless it is usually at least as efficient (if not more) to call this method as to do it fully in calling code.

Returns:
Prefix-qualified name of the current element; essentially 'prefix:localName' if the element has a prefix, or 'localName' if it does not have one (belongs to the default namespace)

closeCompletely

void closeCompletely()
                     throws javax.xml.stream.XMLStreamException
Method similar to XMLStreamReader.getNamespaceContext(), except that this method also does close the underlying input source if it has not yet been closed. It is generally preferable to call this method if the parsing ends in an exception; and for some input sources (when passing a File or URL for factory method) it has to be called as the application does not have access to the actually input source (InputStream opened from a URL and so on).

Throws:
javax.xml.stream.XMLStreamException


Copyright © 2005-2013 Oracle Corporation. All Rights Reserved.