org.codehaus.stax2

Interface LocationInfo

All Known Implementing Classes:

DOMWrappingReader, Stax2ReaderAdapter, Stax2ReaderImpl

public interface LocationInfo

Interface that specifies additional access methods for accessing full location information of an input location within a stream reader. Access interface may be directly implemented by the reader, or by another (reusable or per-call-instantiated) helper object.

Note: instances of LocationInfo are only guaranteed to persist as long as the (stream) reader points to the current element (whatever it is). After next call to streamReader.next, it it possible that the previously accessed LocationInfo points to the old information, new information, or may even contain just garbage. That is, for each new event, getLocationInfo should be called separately.

Method Summary

Methods

Modifier and Type	Method and Description
XMLStreamLocation2	getCurrentLocation() A method that returns the current location of the stream reader at the input source.
long	getEndingByteOffset() Method that can be used to get exact byte offset (number of bytes read from the stream right before getting to this location) in the stream that is pointed to by this reader, right after the end of the current event.
long	getEndingCharOffset() Method that can be used to get exact character offset (number of chars read from the stream right before getting to this location) in the stream that is pointed to by this reader, right after the end of the current event.
XMLStreamLocation2	getEndLocation() An optional method that either returns the location object that points the ending position of the current event, or null if implementation does not keep track of it (some may return only start location; and some no location at all).
Location	getLocation()
long	getStartingByteOffset() Method that can be used to get exact byte offset (number of bytes read from the stream right before getting to this location) in the stream that is pointed to by this reader, right before the start of the current event.
long	getStartingCharOffset() Method that can be used to get exact character offset (number of chars read from the stream right before getting to this location) in the stream that is pointed to by this reader, right before the start of the current event.
XMLStreamLocation2	getStartLocation() An optional method that either returns the location object that points the starting position of the current event, or null if implementation does not keep track of it (some may return only end location; and some no location at all).

Method Detail

getStartingByteOffset

long getStartingByteOffset()

Method that can be used to get exact byte offset (number of bytes read from the stream right before getting to this location) in the stream that is pointed to by this reader, right before the start of the current event.

Note: this value MAY be the same as the one returned by getStartingCharOffset(), but usually only for single-byte character streams (Ascii, ISO-Latin).

Returns:

Byte offset (== number of bytes reader so far) within the underlying stream, if the stream and stream reader are able to provide this (separate from the character offset, for variable-byte encodings); -1 if not.

getStartingCharOffset

long getStartingCharOffset()

Method that can be used to get exact character offset (number of chars read from the stream right before getting to this location) in the stream that is pointed to by this reader, right before the start of the current event.

Note: this value MAY be the same as the one returned by getStartingByteOffset(); this is the case for single-byte character streams (Ascii, ISO-Latin), as well as for streams for which byte offset information is not available (Readers, Strings).

Returns:

Character offset (== number of bytes reader so far) within the underlying stream, if the stream and stream reader are able to provide this (separate from byte offset, for variable-byte encodings); -1 if not.

getEndingByteOffset

long getEndingByteOffset()
                         throws XMLStreamException

Method that can be used to get exact byte offset (number of bytes read from the stream right before getting to this location) in the stream that is pointed to by this reader, right after the end of the current event.

Note: this value MAY be the same as the one returned by getEndingCharOffset(), but usually only for single-byte character streams (Ascii, ISO-Latin).

Note: for lazy-loading implementations, calling this method may require the underlying stream to be advanced and contents parsed; this is why it is possible that an exception be thrown.

Returns:

Byte offset (== number of bytes reader so far) within the underlying stream, if the stream and stream reader are able to provide this (separate from the character offset, for variable-byte encodings); -1 if not.

Throws:

XMLStreamException

getEndingCharOffset

long getEndingCharOffset()
                         throws XMLStreamException

Method that can be used to get exact character offset (number of chars read from the stream right before getting to this location) in the stream that is pointed to by this reader, right after the end of the current event.

Note: this value MAY be the same as the one returned by getEndingByteOffset(); this is the case for single-byte character streams (Ascii, ISO-Latin), as well as for streams for which byte offset information is not available (Readers, Strings).

Note: for lazy-loading implementations, calling this method may require the underlying stream to be advanced and contents parsed; this is why it is possible that an exception be thrown.

Returns:

Character offset (== number of bytes reader so far) within the underlying stream, if the stream and stream reader are able to provide this (separate from byte offset, for variable-byte encodings); -1 if not.

Throws:

XMLStreamException

getLocation

Location getLocation()

getStartLocation

XMLStreamLocation2 getStartLocation()

An optional method that either returns the location object that points the starting position of the current event, or null if implementation does not keep track of it (some may return only end location; and some no location at all).

Note: since it is assumed that the start location must either have been collected by now, or is not accessible (i.e. implementation [always] returns null), no exception is allowed to be throws, as no parsing should ever need to be done (unlike with getEndLocation()).

Returns:

Location of the first character of the current event in the input source (which will also be the starting location of the following event, if any, or EOF if not), or null (if implementation does not track locations).

getCurrentLocation

XMLStreamLocation2 getCurrentLocation()

A method that returns the current location of the stream reader at the input source. This is somewhere between the start and end locations (inclusive), depending on how parser does it parsing (for non-lazy implementations it's always the end location; for others something else).

Since this location information should always be accessible, no further parsing is to be done, and no exceptions can be thrown.

Returns:

Location of the next character reader will parse in the input source.

getEndLocation

XMLStreamLocation2 getEndLocation()
                                  throws XMLStreamException

An optional method that either returns the location object that points the ending position of the current event, or null if implementation does not keep track of it (some may return only start location; and some no location at all).

Note: since some implementations may not yet know the end location (esp. ones that do lazy loading), this call may require further parsing. As a result, this method may throw a parsing or I/O errors.

Returns:

Location right after the end of the current event (which will also be the start location of the next event, if any, or of EOF otherwise).

Throws:

XMLStreamException - If the stream reader had to advance to the end of the event (to find the location), it may encounter a parsing (or I/O) error; if so, that gets thrown