Therefore, limit - offset is a correct way to calculate length of the entire buffer, which is what this class has always used.
This is exactly wrong: The lengthz of the "valid" area inside the buffer is always limit()-position() [see javadocs of wrap()]. If arrayOffset()!=0, position() may still be 0 (because the arrayoffset is only used when wrapping byte arrays. The arrayOffset() defines the postion in the underlying array that defines the buffer's position()==0 (see javadocs).
This error is mostly no problem for dynamical allocated array buffers (as most users use), because arrayOffset() is always 0 (I have never seen a buffer with offset != 0)
A problem also occurs if you wrap an array with wrap(, offset, length). the offset there is not the arrayOffset(), it is the position()! And length is after wrapping remaining(). The capacity() is the array length. Therefore it is really a bug. You deprecated it, that's good, but it should be fixed, it does not work correct.
For verifying, read the source code of ByteBuffer and HeapByteBuffer from src.zip in your jdk distrib and of course the javadocs.
So just to repeat, the correct code would be:
- start postion in array=arrayOffset()+position()
This is how the IdentityEncode for Payloads works. So deprecate and fix it.
If we really want to work with buffers, the correct way to implement this would be that the whole class implements CharsetEncoder.