[
https://issues.apache.org/jira/browse/LUCENE-4314?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13438060#comment-13438060
]
Franco Callari commented on LUCENE-4314:
----------------------------------------
There we go...
---
lucene-4.0.0-BETA/core/src/java/org/apache/lucene/search/DocIdSetIterator.java
2012-06-11 15:46:14.000000000 -0400
+++
/tmp/lucene-fix/core/src/java/org/apache/lucene/search/DocIdSetIterator.java
2012-08-20 14:25:55.000000000 -0400
@@ -60,13 +60,17 @@
*/
public abstract int nextDoc() throws IOException;
- /**
- * Advances to the first beyond (see NOTE below) the current whose document
- * number is greater than or equal to <i>target</i>. Returns the current
- * document number or {@link #NO_MORE_DOCS} if there are no more docs in the
- * set.
+ /**
+ * Advances to the first beyond the current whose document number is greater
+ * than or equal to <i>target</i>, and returns the document number itself.
+ * Exhausts the iterator and returns {@link #NO_MORE_DOCS} if <i>target</i>
+ * is greater than the highest document number in the set.
* <p>
- * Behaves as if written:
+ * The behavior of this method is <b>undefined</b> when called with
+ * <code> target ≤ current</code>, or after the iterator has exhausted.
+ * Both cases may result in unpredicted behavior.
+ * <p>
+ * When <code> target > current</code> it behaves as if written:
*
* <pre>
* int advance(int target) {
@@ -79,18 +83,12 @@
*
* Some implementations are considerably more efficient than that.
* <p>
- * <b>NOTE:</b> when <code> target ≤ current</code> implementations may
opt
- * not to advance beyond their current {@link #docID()}.
- * <p>
* <b>NOTE:</b> this method may be called with {@link #NO_MORE_DOCS} for
* efficiency by some Scorers. If your implementation cannot efficiently
* determine that it should exhaust, it is recommended that you check for
that
* value in each call to this method.
* <p>
- * <b>NOTE:</b> after the iterator has exhausted you should not call this
- * method, as it may result in unpredicted behavior.
- * <p>
- *
+ *
* @since 2.9
*/
public abstract int advance(int target) throws IOException;
> The specification of DocIdSetIterator is needlessly ambiguous.
> --------------------------------------------------------------
>
> Key: LUCENE-4314
> URL: https://issues.apache.org/jira/browse/LUCENE-4314
> Project: Lucene - Core
> Issue Type: Improvement
> Components: core/search
> Affects Versions: 3.6.1, 4.0-BETA
> Environment: All
> Reporter: Franco Callari
> Labels: index,, iterators
>
> Quoth Lucene at org.apache.lucene.search.DocIdSetIterator.advance:
> "Advances to the first beyond (see NOTE below) the current whose document
> number is greater than or equal to <i>target</i>. [...]
> NOTE:</b> when <code> target ≤ current</code> implementations may opt
> not to advance beyond their current {@link #docID()}."
> However, the same specification contradictorily states that advance must
> behave as if written:
> int advance(int target) {
> int doc;
> while ((doc = nextDoc()) < target) {}
> return doc;
> }
> That is, with at least one call to nextDoc() always made, unconditionally.
> This ambiguity can lead to unexpected behavior. In fact, arguably every user
> of this interface that does not test after every call whether the iterator
> has exhausted AND has advanced is incorrect.
> For example, I myself had one experimental implementation (coded against a
> previous Lucene release) that caused an infinite loop in PhraseScorer.java
> because, following the above specification, it "opted" not to move the
> iterator when advance(target) was called with target < current.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
