Stax2 API 4.2.2 · org.codehaus.stax2.XMLStreamReader2

Modifier and Type	Field and Description
public static final 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).

Method Summary

Modifier and Type	Method and Description
public void	closeCompletely() Method similar to `javax.xml.stream.XMLStreamReader#close`, except that this method also does close the underlying input source if it has not yet been closed.
public 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.
public int	Returns: Number of open elements currently in the reader's stack, including current START_ELEMENT or END_ELEMENT (if pointing to one). 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.
public DTDInfo	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) 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.
public Object	Returns: Value of the feature (possibly null), if supported; null otherwise getFeature(String Name of the feature of which value to get name) Deprecated Should use `getProperty` 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.
public LocationInfo	getLocationInfo()
public NamespaceContext	Returns: Non-transient namespace context as explained above. getNonTransientNamespaceContext() This method returns a namespace context object that contains information identical to that returned by `javax.xml.stream.XMLStreamReader#getNamespaceContext()`, but one that is not transient.
public String	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) getPrefixedName() This method returns "prefix-qualified" name of the current element.
public int	Returns: Number of characters written to the reader getText(Writer Writer to use for writing textual contents w, boolean 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. preserveContents) Method similar to `getText()`, except that it just uses provided Writer to write all textual content, and that it works for wider range of event types.
public boolean	Returns: True, if current event is START_ELEMENT and is based on a parsed empty element; otherwise false 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.
public boolean	isPropertySupported(String name) Method similar to `javax.xml.stream.XMLInputFactory#isPropertySupported`, used to determine whether a property is supported by the Reader instance.
public void	setFeature(String Name of the feature to set name, Object Value to set feature to. value) Deprecated Should use `setProperty` 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.
public boolean	Returns: True, if the specified property was succesfully set to specified value; false if its value was not changed setProperty(String Name of the property to set name, Object Value to set property to. value) Method that can be used to set per-reader properties; a subset of properties one can set via matching `org.codehaus.stax2.XMLInputFactory2` instance.
public void	skipElement() Method that will skip all the contents of the element that the stream currently points to.

Inherited from 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
Inherited from org.codehaus.stax2.validation.Validatable:: setValidationProblemHandler stopValidatingAgainst stopValidatingAgainst validateAgainst

FEATURE_DTD_OVERRIDE	back to summary
public 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). Annotations @Deprecated

Method Detail

closeCompletely back to summary

closeCompletely	back to summary
public void closeCompletely() throws XMLStreamException Method similar to `javax.xml.stream.XMLStreamReader#close`, 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 `java.io.File` or `java.net.URL` for factory method) it has to be called as the application does not have access to the actually input source (`java.io.InputStream` opened from a `java.net.URL` and so on).

public void closeCompletely() throws XMLStreamException

Method similar to javax.xml.stream.XMLStreamReader#close, 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 java.io.File or java.net.URL for factory method) it has to be called as the application does not have access to the actually input source (java.io.InputStream opened from a java.net.URL and so on).

getAttributeInfo	back to summary
public AttributeInfo getAttributeInfo() throws 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.

getDepth	back to summary
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 (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:int Number of open elements currently in the reader's stack, including current START_ELEMENT or END_ELEMENT (if pointing to one).

getDepth

back to summary

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 (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:int: Number of open elements currently in the reader's stack, including current START_ELEMENT or END_ELEMENT (if pointing to one).

getDTDInfo	back to summary
public DTDInfo getDTDInfo() throws 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:DTDInfo 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)

getDTDInfo

back to summary

public DTDInfo getDTDInfo() throws 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:DTDInfo: 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)

getFeature back to summary

getFeature	back to summary
public Object getFeature(String name) Deprecated Should use `getProperty` 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`, not all are: some features are read-only, some write-only Parameters name:String Name of the feature of which value to get Returns:Object Value of the feature (possibly null), if supported; null otherwise Annotations @Deprecated

public Object getFeature(String name)

Deprecated

Should use getProperty 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, not all are: some features are read-only, some write-only

Parameters

name:String: Name of the feature of which value to get

Returns:Object

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

Annotations

@Deprecated

getLocationInfo	back to summary
public LocationInfo getLocationInfo()

getNonTransientNamespaceContext back to summary

getNonTransientNamespaceContext	back to summary
public NamespaceContext getNonTransientNamespaceContext() This method returns a namespace context object that contains information identical to that returned by `javax.xml.stream.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:NamespaceContext Non-transient namespace context as explained above.

public NamespaceContext getNonTransientNamespaceContext()

This method returns a namespace context object that contains information identical to that returned by javax.xml.stream.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:NamespaceContext: Non-transient namespace context as explained above.

getPrefixedName back to summary

getPrefixedName	back to summary
public 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:String 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)

public 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:String: 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)

getText back to summary

getText	back to summary
public int getText(Writer w, boolean preserveContents) throws IOException, XMLStreamException Method similar to `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 `getText()`. Parameters w:Writer Writer to use for writing textual contents preserveContents:boolean 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:int Number of characters written to the reader

public int getText(Writer w, boolean preserveContents) throws IOException, XMLStreamException

Method similar to 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 getText().

Parameters

w:Writer: Writer to use for writing textual contents
preserveContents:boolean: 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:int

Number of characters written to the reader

isEmptyElement back to summary

isEmptyElement	back to summary
public boolean isEmptyElement() throws 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:boolean True, if current event is START_ELEMENT and is based on a parsed empty element; otherwise false

public boolean isEmptyElement() throws 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:boolean: True, if current event is START_ELEMENT and is based on a parsed empty element; otherwise false

isPropertySupported back to summary

isPropertySupported	back to summary
public boolean isPropertySupported(String name) Method similar to `javax.xml.stream.XMLInputFactory#isPropertySupported`, 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.

public boolean isPropertySupported(String name)

Method similar to javax.xml.stream.XMLInputFactory#isPropertySupported, 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.

setFeature back to summary

setFeature	back to summary
public void setFeature(String name, Object value) Deprecated Should use `setProperty` 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`, not all are: some features are read-only, some write-only Parameters name:String Name of the feature to set value:Object Value to set feature to. Annotations @Deprecated

public void setFeature(String name, Object value)

Deprecated

Should use setProperty 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, not all are: some features are read-only, some write-only

Parameters

name:String: Name of the feature to set
value:Object: Value to set feature to.

Annotations

@Deprecated

setProperty back to summary

setProperty	back to summary
public 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 `org.codehaus.stax2.XMLInputFactory2` instance. Exactly which methods are mutable is implementation specific. Parameters name:String Name of the property to set value:Object Value to set property to. Returns:boolean True, if the specified property was succesfully set to specified value; false if its value was not changed Exceptions IllegalArgumentException: if the property is not supported (or recognized) by the stream reader implementation

public 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 org.codehaus.stax2.XMLInputFactory2 instance. Exactly which methods are mutable is implementation specific.

Parameters

name:String: Name of the property to set
value:Object: Value to set property to.

Returns:boolean

True, if the specified property was succesfully set to specified value; false if its value was not changed

Exceptions

IllegalArgumentException:: if the property is not supported (or recognized) by the stream reader implementation

skipElement	back to summary
public void skipElement() throws 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.

public Interface XMLStreamReader2

Field Summary

Method Summary

Field Detail

Method Detail