[GitHub] yshavit opened a new issue #836: documentation on SortedKeyValueIterator::seek is inconsistent

[GitBox <gi...@apache.org>]

yshavit opened a new issue #836: documentation on SortedKeyValueIterator::seek is inconsistent
URL: https://github.com/apache/accumulo/issues/836
 
 
   The JavaDoc on [`SKVI::seek`][1] says:
   
   > An iterator does not have to stop at the end of the range. The whole range is provided so that iterators can make optimizations.
   
   The [non-JavaDoc documentation][2] says something very different:
   
   > It is important to retain the original Range passed to this method to know when this Iterator should stop reading more Key-Value pairs. Ignoring this typically does not affect scans from a Scanner, but it will result in duplicate keys emitting from a BatchScanner if the scanned table has more than one tablet. Best practice is to never emit entries outside the seek range.
   
   These are two very different contracts. The first one says that as an implementer, I don't have to worry about the end of the range for correctness; it's only there if I feel like it'll help me optimize. But the second says that as an implementer, I _should_ worry about the end of the range, at least if not returning duplicates is part of my correctness (which is probably a safe assumption that it should be).
   
   Whichever of these is correct, the other one should be brought in line.
   
   [1]: https://github.com/apache/accumulo/blob/master/core/src/main/java/org/apache/accumulo/core/iterators/SortedKeyValueIterator.java#L81-L82
   [2]: https://accumulo.apache.org/docs/2.x/development/iterators#seek

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services