Implementation of XMLStreamReader.getLocation() inconsistent with javadoc

[klease]

Hello, I'm contributing to the Apache Camel project where we use woodstox as the preferred Stax implementation. In particular we rely on XMLStreamReader.getLocation().getCharacterOffset() and the fact that it returns the position at the start of the event, for example at the beginning of the start or end tag. The built-in implementation of XMLStreamReader in the JDK returns the offset at the end of the tag. The javadoc for the JDK API doesn't seem explicit. But I notice that the javadoc for the Woodstox implementation class (com.ctc.wstx.sr.BasicStreamReader) states:

public final Location getLocation() Description copied from class: StreamScanner Returns location of last properly parsed token; as per StAX specs, apparently needs to be the end of current event, which is the same as the start of the following event (or EOF if that's next).

But the implementation of BasicStreamReader returns the start location.

I'm not suggesting you change the implementation, since Camel is currently relying on it, but the javadoc should be corrected in that case. -Karen Lease

[cowtowncoder]

I agree that Javadoc should explain behavior as it actually exists.

I think Stax2 extension API has different methods for "current" (which would be somewhere between start and end, depending on if lazy parsing enabled) and "start" location, making it bit more explicit.

I am happy to change wording but also if you or anyone else has time, PRs are always a good way to go :) (I can review things faster than write)