Interface LocationInfo
- All Known Implementing Classes:
DOMWrappingReader
,Stax2ReaderAdapter
,Stax2ReaderImpl
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
Modifier and TypeMethodDescriptionA method that returns the current location of the stream reader at the input source.long
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
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.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).long
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
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.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 Details
-
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
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
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
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
-