Index: CHANGES.txt =================================================================== --- CHANGES.txt (revision 775940) +++ CHANGES.txt (working copy) @@ -28,7 +28,7 @@ code to implement this method. If you already extend IndexSearcher, no further changes are needed to use Collector. (Shai Erera via Mike McCandless) - + Changes in runtime behavior 1. LUCENE-1424: QueryParser now by default uses constant score query @@ -135,6 +135,16 @@ not make sense for all subclasses of MultiTermQuery. Check individual subclasses to see if they support #getTerm(). (Mark Miller) +14. LUCENE-1614: DocIdSetIterator's next() and skipTo() were deprecated in favor + of the new nextDoc() and advance(). The new methods return the doc Id they + landed on, which should save the extra call to doc(). + For easy migration of the code, you can change the calls to next() to + nextDoc() != DocIdSetIterator.NO_MORE_DOCS and similarly for skipTo(). + However it is advised that you take advantage of the returned doc Id and not + call doc() following those two. + NOTE: in 3.0 doc() will be expected to return DocIdSetIterator.NO_MORE_DOCS + when the iterator has exhausted. (Shai Erera vs. Mike McCandless) + Bug fixes 1. LUCENE-1415: MultiPhraseQuery has incorrect hashCode() and equals() Index: contrib/miscellaneous/src/test/org/apache/lucene/misc/ChainedFilterTest.java =================================================================== --- contrib/miscellaneous/src/test/org/apache/lucene/misc/ChainedFilterTest.java (revision 775940) +++ contrib/miscellaneous/src/test/org/apache/lucene/misc/ChainedFilterTest.java (working copy) @@ -94,15 +94,17 @@ final Filter f = chain[i]; // create old BitSet-based Filter as wrapper oldFilters[i] = new Filter() { + /** @deprecated */ public BitSet bits(IndexReader reader) throws IOException { BitSet bits = new BitSet(reader.maxDoc()); - DocIdSetIterator it = f.getDocIdSet(reader).iterator(); - while(it.next()) { - bits.set(it.doc()); + DocIdSetIterator it = f.getDocIdSet(reader).iterator(); + int doc; + while((doc = it.nextDoc()) != DocIdSetIterator.NO_MORE_DOCS) { + bits.set(doc); } return bits; } - }; + }; } return oldFilters; } Index: src/java/org/apache/lucene/index/DocumentsWriter.java =================================================================== --- src/java/org/apache/lucene/index/DocumentsWriter.java (revision 775940) +++ src/java/org/apache/lucene/index/DocumentsWriter.java (working copy) @@ -19,6 +19,7 @@ import org.apache.lucene.analysis.Analyzer; import org.apache.lucene.document.Document; +import org.apache.lucene.search.DocIdSetIterator; import org.apache.lucene.search.Similarity; import org.apache.lucene.search.Query; import org.apache.lucene.search.IndexSearcher; @@ -983,11 +984,11 @@ int limit = ((Integer) entry.getValue()).intValue(); Weight weight = query.weight(searcher); Scorer scorer = weight.scorer(reader); - while(scorer.next()) { - final int docID = scorer.doc(); - if (docIDStart + docID >= limit) + int doc; + while((doc = scorer.nextDoc()) != DocIdSetIterator.NO_MORE_DOCS) { + if (docIDStart + doc >= limit) break; - reader.deleteDocument(docID); + reader.deleteDocument(doc); any = true; } } Index: src/java/org/apache/lucene/search/BooleanScorer.java =================================================================== --- src/java/org/apache/lucene/search/BooleanScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/BooleanScorer.java (working copy) @@ -87,7 +87,7 @@ Collector collector, SubScorer next) throws IOException { this.scorer = scorer; - this.done = !scorer.next(); + this.done = scorer.nextDoc() == NO_MORE_DOCS; this.required = required; this.prohibited = prohibited; this.collector = collector; @@ -138,7 +138,7 @@ } public void score(Collector collector) throws IOException { - next(); + nextDoc(); score(collector, Integer.MAX_VALUE); } @@ -209,7 +209,14 @@ public int doc() { return current.doc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { + // TODO (3.0): set current.doc to NO_MORE_DOCS and also remove sub.done and + // take advantage of NO_MORE_DOCS. boolean more; do { while (bucketTable.first != null) { // more queued @@ -220,7 +227,7 @@ if ((current.bits & prohibitedMask) == 0 && (current.bits & requiredMask) == requiredMask && current.coord >= minNrShouldMatch) { - return true; + return current.doc; } } @@ -230,9 +237,12 @@ for (SubScorer sub = scorers; sub != null; sub = sub.next) { Scorer scorer = sub.scorer; sub.collector.setScorer(scorer); - while (!sub.done && scorer.doc() < end) { - sub.collector.collect(scorer.doc()); - sub.done = !scorer.next(); + // Check sub.done since if it's true we will hit NPE in doc(). + int doc = sub.done ? -1 : scorer.doc(); + while (!sub.done && doc < end) { + sub.collector.collect(doc); + doc = scorer.nextDoc(); + sub.done = doc == NO_MORE_DOCS; } if (!sub.done) { more = true; @@ -240,9 +250,9 @@ } } while (bucketTable.first != null || more); - return false; + return NO_MORE_DOCS; } - + public float score() { if (coordFactors == null) { computeCoordFactors(); @@ -284,14 +294,24 @@ return doc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { return false; } + public int nextDoc() throws IOException { + return NO_MORE_DOCS; + } + + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { return false; } + public int advance(int target) throws IOException { + return NO_MORE_DOCS; + } + } /** A simple hash table of document scores within a range. */ @@ -350,10 +370,15 @@ } } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) { throw new UnsupportedOperationException(); } + public int advance(int target) throws IOException { + throw new UnsupportedOperationException(); + } + public Explanation explain(int doc) { throw new UnsupportedOperationException(); } Index: src/java/org/apache/lucene/search/BooleanScorer2.java =================================================================== --- src/java/org/apache/lucene/search/BooleanScorer2.java (revision 775940) +++ src/java/org/apache/lucene/search/BooleanScorer2.java (working copy) @@ -164,12 +164,20 @@ public int doc() { return scorer.doc(); } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - return scorer.next(); + return scorer.nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + return scorer.nextDoc(); + } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int docNr) throws IOException { - return scorer.skipTo(docNr); + return scorer.advance(docNr) != NO_MORE_DOCS; } + public int advance(int target) throws IOException { + return scorer.advance(target); + } public Explanation explain(int docNr) throws IOException { return scorer.explain(docNr); } @@ -339,8 +347,9 @@ initCountingSumScorer(); } collector.setScorer(this); - while (countingSumScorer.next()) { - collector.collect(countingSumScorer.doc()); + int doc; + while ((doc = countingSumScorer.nextDoc()) != NO_MORE_DOCS) { + collector.collect(doc); } } } @@ -371,44 +380,45 @@ collector.setScorer(this); while (docNr < max) { collector.collect(docNr); - if (!countingSumScorer.next()) { + if ((docNr = countingSumScorer.nextDoc()) == NO_MORE_DOCS) { return false; } - docNr = countingSumScorer.doc(); } return true; } public int doc() { return countingSumScorer.doc(); } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { if (countingSumScorer == null) { initCountingSumScorer(); } - return countingSumScorer.next(); + return countingSumScorer.nextDoc(); } - + public float score() throws IOException { coordinator.nrMatchers = 0; float sum = countingSumScorer.score(); return sum * coordinator.coordFactors[coordinator.nrMatchers]; } - /** Skips to the first match beyond the current whose document number is - * greater than or equal to a given target. - * - *

When this method is used the {@link #explain(int)} method should not be used. - * - * @param target The target document number. - * @return true iff there is such a match. - */ + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { if (countingSumScorer == null) { initCountingSumScorer(); } - return countingSumScorer.skipTo(target); + return countingSumScorer.advance(target); } - + /** Throws an UnsupportedOperationException. * TODO: Implement an explanation of the coordination factor. * @param doc The document number for the explanation. Index: src/java/org/apache/lucene/search/ConjunctionScorer.java =================================================================== --- src/java/org/apache/lucene/search/ConjunctionScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/ConjunctionScorer.java (working copy) @@ -43,41 +43,52 @@ public int doc() { return lastDoc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { if (firstTime) - return init(0); + return init(0) ? lastDoc : NO_MORE_DOCS; else if (more) - more = scorers[(scorers.length-1)].next(); - return doNext(); + more = scorers[(scorers.length - 1)].nextDoc() != NO_MORE_DOCS; + return doNext() ? lastDoc : NO_MORE_DOCS; } - + private boolean doNext() throws IOException { - int first=0; + // TODO (3.0): take advantage of doc() returning NO_MORE_DOCS. + int first = 0; Scorer lastScorer = scorers[scorers.length-1]; Scorer firstScorer; while (more && (firstScorer=scorers[first]).doc() < (lastDoc=lastScorer.doc())) { - more = firstScorer.skipTo(lastDoc); + more = firstScorer.advance(lastDoc) != NO_MORE_DOCS; lastScorer = firstScorer; - first = (first == (scorers.length-1)) ? 0 : first+1; + first = (first == (scorers.length - 1)) ? 0 : first + 1; } return more; } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { if (firstTime) - return init(target); + return init(target) ? lastDoc : NO_MORE_DOCS; else if (more) - more = scorers[(scorers.length-1)].skipTo(target); - return doNext(); + more = scorers[(scorers.length-1)].advance(target) != NO_MORE_DOCS; + return doNext() ? lastDoc : NO_MORE_DOCS; } - + // Note... most of this could be done in the constructor // thus skipping a check for firstTime per call to next() and skipTo() private boolean init(int target) throws IOException { - firstTime=false; - more = scorers.length>1; - for (int i=0; i 1; + for (int i = 0; i < scorers.length; i++) { + more = (target == 0 ? scorers[i].nextDoc() : scorers[i].advance(target)) != NO_MORE_DOCS; if (!more) return false; } @@ -101,8 +112,8 @@ // Keep last scorer in it's last place (it will be the first // to be skipped on), but reverse all of the others so that // they will be skipped on in order of original high skip. - int end=(scorers.length-1); - for (int i=0; i<(end>>1); i++) { + int end = (scorers.length - 1); + for (int i = 0; i < (end >> 1); i++) { Scorer tmp = scorers[i]; scorers[i] = scorers[end-i-1]; scorers[end-i-1] = tmp; Index: src/java/org/apache/lucene/search/ConstantScoreQuery.java =================================================================== --- src/java/org/apache/lucene/search/ConstantScoreQuery.java (revision 775940) +++ src/java/org/apache/lucene/search/ConstantScoreQuery.java (working copy) @@ -84,7 +84,7 @@ public Explanation explain(IndexReader reader, int doc) throws IOException { ConstantScorer cs = (ConstantScorer)scorer(reader); - boolean exists = cs.docIdSetIterator.skipTo(doc) && (cs.docIdSetIterator.doc() == doc); + boolean exists = cs.docIdSetIterator.advance(doc) == doc; ComplexExplanation result = new ComplexExplanation(); @@ -116,10 +116,15 @@ docIdSetIterator = filter.getDocIdSet(reader).iterator(); } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - return docIdSetIterator.next(); + return docIdSetIterator.nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + return docIdSetIterator.nextDoc(); + } + public int doc() { return docIdSetIterator.doc(); } @@ -128,24 +133,26 @@ return theScore; } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { - return docIdSetIterator.skipTo(target); + return docIdSetIterator.advance(target) != NO_MORE_DOCS; } + public int advance(int target) throws IOException { + return docIdSetIterator.advance(target); + } + public Explanation explain(int doc) throws IOException { throw new UnsupportedOperationException(); } } - protected Weight createWeight(Searcher searcher) { return new ConstantScoreQuery.ConstantWeight(searcher); } - /** Prints a user-readable version of this query. */ - public String toString(String field) - { + public String toString(String field) { return "ConstantScore(" + filter.toString() + (getBoost()==1.0 ? ")" : "^" + getBoost()); } @@ -165,6 +172,3 @@ } } - - - Index: src/java/org/apache/lucene/search/DisjunctionMaxScorer.java =================================================================== --- src/java/org/apache/lucene/search/DisjunctionMaxScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/DisjunctionMaxScorer.java (working copy) @@ -48,35 +48,51 @@ * @param scorer the scorer of a subquery of our associated DisjunctionMaxQuery */ public void add(Scorer scorer) throws IOException { - if (scorer.next()) { // Initialize and retain only if it produces docs - subScorers.add(scorer); - more = true; - } + if (scorer.nextDoc() != NO_MORE_DOCS) { // Initialize and retain only if it produces docs + subScorers.add(scorer); + more = true; + } } - /** Generate the next document matching our associated DisjunctionMaxQuery. + /** + * Generate the next document matching our associated DisjunctionMaxQuery. + * * @return true iff there is a next document + * @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - if (!more) return false; - if (firstTime) { - heapify(); - firstTime = false; - return true; // more would have been false if no subScorers had any docs - } - // Increment all generators that generated the last doc and adjust the heap. - int lastdoc = ((Scorer) subScorers.get(0)).doc(); - do { - if (((Scorer) subScorers.get(0)).next()) - heapAdjust(0); - else { - heapRemoveRoot(); - if (subScorers.isEmpty()) return (more = false); - } - } while ( ((Scorer) subScorers.get(0)).doc()==lastdoc ); - return true; + return nextDoc() != NO_MORE_DOCS; } + /** + * Generate the next document matching our associated DisjunctionMaxQuery. + * + * @return the next document if exists or -1 otherwise. + */ + public int nextDoc() throws IOException { + if (!more) return NO_MORE_DOCS; + if (firstTime) { + heapify(); + firstTime = false; + // more would have been false if no subScorers had any docs + return ((Scorer) subScorers.get(0)).doc(); + } + // Increment all generators that generated the last doc and adjust the heap. + int lastdoc = ((Scorer) subScorers.get(0)).doc(); + do { + if (((Scorer) subScorers.get(0)).nextDoc() != NO_MORE_DOCS) { + heapAdjust(0); + } else { + heapRemoveRoot(); + if (subScorers.isEmpty()) { + more = false; + return NO_MORE_DOCS; + } + } + } while (((Scorer) subScorers.get(0)).doc() == lastdoc); + return ((Scorer) subScorers.get(0)).doc(); + } + /** Determine the current document number. Initially invalid, until {@link #next()} is called the first time. * @return the document number of the currently generated document */ @@ -107,28 +123,49 @@ } } - /** Advance to the first document beyond the current whose number is greater than or equal to target. - * @param target the minimum number of the next desired document - * @return true iff there is a document to be generated whose number is at least target + /** + * Advance to the first document beyond the current whose number is greater + * than or equal to target. + * + * @param target + * the minimum number of the next desired document + * @return true iff there is a document to be generated whose number is at + * least target + * @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { - if (firstTime) { - if (!more) return false; - heapify(); - firstTime = false; - } + return advance(target) != NO_MORE_DOCS; + } - while (subScorers.size()>0 && ((Scorer)subScorers.get(0)).doc() 0 && ((Scorer) subScorers.get(0)).doc() < target) { + if (((Scorer)subScorers.get(0)).advance(target) != NO_MORE_DOCS) { + heapAdjust(0); + } else { + heapRemoveRoot(); + } + } + if (subScorers.size() == 0) { + more = false; + return NO_MORE_DOCS; + } + return ((Scorer) subScorers.get(0)).doc(); } - + /** Explain a score that we computed. UNSUPPORTED -- see explanation capability in DisjunctionMaxQuery. * @param doc the number of a document we scored * @return the Explanation for our score Index: src/java/org/apache/lucene/search/DisjunctionSumScorer.java =================================================================== --- src/java/org/apache/lucene/search/DisjunctionSumScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/DisjunctionSumScorer.java (working copy) @@ -102,7 +102,7 @@ scorerDocQueue = new ScorerDocQueue(nrScorers); while (si.hasNext()) { Scorer se = (Scorer) si.next(); - if (se.next()) { // doc() method will be used in scorerDocQueue. + if (se.nextDoc() != NO_MORE_DOCS) { // doc() method will be used in scorerDocQueue. scorerDocQueue.insert(se); } } @@ -124,7 +124,7 @@ */ public void score(Collector collector) throws IOException { collector.setScorer(this); - while (next()) { + while (nextDoc() != NO_MORE_DOCS) { collector.collect(currentDoc); } } @@ -153,18 +153,22 @@ collector.setScorer(this); while (currentDoc < max) { collector.collect(currentDoc); - if (!next()) { + if (nextDoc() == NO_MORE_DOCS) { return false; } } return true; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - return (scorerDocQueue.size() >= minimumNrMatchers) - && advanceAfterCurrent(); + return nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + // TODO (3.0): set currentDoc to NO_MORE_DOCS. + return scorerDocQueue.size() >= minimumNrMatchers && advanceAfterCurrent() ? currentDoc : NO_MORE_DOCS; + } /** Advance all subscorers after the current document determined by the * top of the scorerDocQueue. @@ -176,7 +180,7 @@ *
In case there is a match, currentDoc, currentSumScore, * and nrMatchers describe the match. * - * @todo Investigate whether it is possible to use skipTo() when + * TODO: Investigate whether it is possible to use skipTo() when * the minimum number of matchers is bigger than one, ie. try and use the * character of ConjunctionScorer for the minimum number of matchers. * Also delay calling score() on the sub scorers until the minimum number of @@ -190,7 +194,7 @@ currentScore = scorerDocQueue.topScore(); nrMatchers = 1; do { // Until all subscorers are after currentDoc - if (! scorerDocQueue.topNextAndAdjustElsePop()) { + if (!scorerDocQueue.topNextAndAdjustElsePop()) { if (scorerDocQueue.size() == 0) { break; // nothing more to advance, check for last match. } @@ -224,31 +228,53 @@ return nrMatchers; } - /** Skips to the first match beyond the current whose document number is - * greater than or equal to a given target. - *
When this method is used the {@link #explain(int)} method should not be used. - *
The implementation uses the skipTo() method on the subscorers. - * @param target The target document number. + /** + * Skips to the first match beyond the current whose document number is + * greater than or equal to a given target.
+ * When this method is used the {@link #explain(int)} method should not be + * used.
+ * The implementation uses the skipTo() method on the subscorers. + * + * @param target + * The target document number. * @return true iff there is such a match. + * @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + /** + * Advances to the first match beyond the current whose document number is + * greater than or equal to a given target.
+ * When this method is used the {@link #explain(int)} method should not be + * used.
+ * The implementation uses the skipTo() method on the subscorers. + * + * @param target + * The target document number. + * @return the document whose number is greater than or equal to the given + * target, or -1 if none exist. + */ + public int advance(int target) throws IOException { + // TODO (3.0): set currentDoc to NO_MORE_DOCS if (scorerDocQueue.size() < minimumNrMatchers) { - return false; + return NO_MORE_DOCS; } if (target <= currentDoc) { - return true; + return currentDoc; } do { if (scorerDocQueue.topDoc() >= target) { - return advanceAfterCurrent(); - } else if (! scorerDocQueue.topSkipToAndAdjustElsePop(target)) { + return advanceAfterCurrent() ? currentDoc : NO_MORE_DOCS; + } else if (!scorerDocQueue.topSkipToAndAdjustElsePop(target)) { if (scorerDocQueue.size() < minimumNrMatchers) { - return false; + return NO_MORE_DOCS; } } } while (true); } - + /** @return An explanation for the score of a given document. */ public Explanation explain(int doc) throws IOException { Explanation res = new Explanation(); Index: src/java/org/apache/lucene/search/DocIdSetIterator.java =================================================================== --- src/java/org/apache/lucene/search/DocIdSetIterator.java (revision 775940) +++ src/java/org/apache/lucene/search/DocIdSetIterator.java (working copy) @@ -20,30 +20,113 @@ import java.io.IOException; /** - * This abstract class defines methods to iterate over a set of - * non-decreasing doc ids. + * This abstract class defines methods to iterate over a set of non-decreasing + * doc ids. Note that this class assumes it iterates on doc Ids, and therefore + * {@link #NO_MORE_DOCS} is set to {@link Integer#MAX_VALUE} to be used as a + * sentinel object. Implementations of this class are expected to consider + * {@link Integer#MAX_VALUE} as an invalid value. */ public abstract class DocIdSetIterator { - /** Returns the current document number.

This is invalid until {@link - #next()} is called for the first time.*/ - public abstract int doc(); - - /** Moves to the next docId in the set. Returns true, iff - * there is such a docId. */ - public abstract boolean next() throws IOException; - - /** Skips entries to the first beyond the current whose document number is - * greater than or equal to target.

Returns true iff there is such - * an entry.

Behaves as if written: 

-     *   boolean skipTo(int target) {
-     *     do {
-     *       if (!next())
-     *         return false;
-     *     } while (target > doc());
-     *     return true;
-     *   }
-     *
- * Some implementations are considerably more efficient than that. - */ - public abstract boolean skipTo(int target) throws IOException; + + // TODO (3.0): review the javadocs and remove any references to 3.0. + + /** + * When returned by {@link #nextDoc()}, {@link #advance(int)} and + * {@link #doc()} it means there are no more docs in the iterator. + */ + public static final int NO_MORE_DOCS = Integer.MAX_VALUE; + + /** + * Returns the current document number. Calling this before calling + * {@link #nextDoc()} or {@link #advance(int)} may return an unspecified + * result. + * + *

+ * NOTE: starting with 3.0, when the iterator has exhausted, this + * method is expected to return {@link #NO_MORE_DOCS}. + */ + public abstract int doc(); + + /** + * Moves to the next docId in the set. Returns true, iff there is such a + * docId. + * + * @deprecated use {@link #nextDoc()} instead. This will be removed in 3.0 + */ + public abstract boolean next() throws IOException; + + /** Skips entries to the first beyond the current whose document number is + * greater than or equal to target.

Returns true iff there is such + * an entry.

Behaves as if written: 

+   *   boolean skipTo(int target) {
+   *     do {
+   *       if (!next())
+   *         return false;
+   *     } while (target > doc());
+   *     return true;
+   *   }
+   *
+ * Some implementations are considerably more efficient than that. + * + * @deprecated use {@link #advance(int)} instead. This will be removed in 3.0 + */ + public abstract boolean skipTo(int target) throws IOException; + + /** + * Advances to the next document in the set and returns the doc it is + * currently on, or {@link #NO_MORE_DOCS} if there are no more docs in the + * set. NOTE: currently, when the iterator has exhausted, the result of + * {@link #doc()} is unspecified. This will change in 3.0 when {@link #doc()} + * will return {@link #NO_MORE_DOCS} as well.
+ * + * NOTE: in 3.0 this method will become abstract, following the removal + * of {@link #next()}. For backward compatibility it is implemented as: + * + * 
+   * public int nextDoc() throws IOException {
+   *   return next() ? doc() : -1;
+   * }
+   *
+ * + * @since 2.9 + */ + public int nextDoc() throws IOException { + return next() ? doc() : NO_MORE_DOCS; + } + + /** + * Advances to the first beyond the current whose document number is greater + * than or equal to target. Returns the current document number or + * {@link #NO_MORE_DOCS} if there are no more docs in the set. + *

+ * Behaves as if written: + * + * 

+   * int advance(int target) {
+   *   int doc;
+   *   while ((doc = nextDoc()) < target) {
+   *   }
+   *   return doc;
+   * }
+   *
+ * + * Some implementations are considerably more efficient than that. + * + * NOTE: certain implemenations may return a different value (each + * time) if called several times in a row with the same target. + * + * NOTE: if this method returns {@link #NO_MORE_DOCS}, the result of + * {@link #doc()} is unspecified (but will change in 3.0). + * + * NOTE: in 3.0 this method will become abstract, following the removal + * of {@link #skipTo(int)}. + * + * @since 2.9 + */ + public int advance(int target) throws IOException { + int doc; + while ((doc = nextDoc()) < target) {} + return doc; + } + } Index: src/java/org/apache/lucene/search/FieldCacheRangeFilter.java =================================================================== --- src/java/org/apache/lucene/search/FieldCacheRangeFilter.java (revision 775940) +++ src/java/org/apache/lucene/search/FieldCacheRangeFilter.java (working copy) @@ -163,32 +163,41 @@ return doc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() { try { do { doc++; } while (fcsi.order[doc] > inclusiveUpperPoint || fcsi.order[doc] < inclusiveLowerPoint); - return true; } catch (ArrayIndexOutOfBoundsException e) { - doc = Integer.MAX_VALUE; - return false; + doc = NO_MORE_DOCS; } + return doc; } - + + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) { try { doc = target; while (fcsi.order[doc] > inclusiveUpperPoint || fcsi.order[doc] < inclusiveLowerPoint) { doc++; } - return true; } catch (ArrayIndexOutOfBoundsException e) { - doc = Integer.MAX_VALUE; - return false; + doc = NO_MORE_DOCS; } + return doc; } + } } } Index: src/java/org/apache/lucene/search/FieldCacheTermsFilter.java =================================================================== --- src/java/org/apache/lucene/search/FieldCacheTermsFilter.java (revision 775940) +++ src/java/org/apache/lucene/search/FieldCacheTermsFilter.java (working copy) @@ -17,12 +17,11 @@ * limitations under the License. */ +import java.io.IOException; + import org.apache.lucene.index.IndexReader; -import org.apache.lucene.index.TermDocs; // for javadoc import org.apache.lucene.util.OpenBitSet; -import java.io.IOException; - /** * A {@link Filter} that only accepts documents whose single * term value in the specified field is contained in the @@ -137,29 +136,35 @@ return doc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() { try { - do { - doc++; - } while (!openBitSet.fastGet(fcsi.order[doc])); - return true; + while (!openBitSet.fastGet(fcsi.order[++doc])) {} } catch (ArrayIndexOutOfBoundsException e) { - doc = Integer.MAX_VALUE; - return false; + doc = NO_MORE_DOCS; } + return doc; } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) { try { doc = target; while (!openBitSet.fastGet(fcsi.order[doc])) { doc++; } - return true; } catch (ArrayIndexOutOfBoundsException e) { - doc = Integer.MAX_VALUE; - return false; + doc = NO_MORE_DOCS; } + return doc; } } } Index: src/java/org/apache/lucene/search/FilteredDocIdSetIterator.java =================================================================== --- src/java/org/apache/lucene/search/FilteredDocIdSetIterator.java (revision 775940) +++ src/java/org/apache/lucene/search/FilteredDocIdSetIterator.java (working copy) @@ -25,7 +25,6 @@ * mechanism on an underlying DocIdSetIterator. See {@link * FilteredDocIdSet}. */ - public abstract class FilteredDocIdSetIterator extends DocIdSetIterator { protected DocIdSetIterator _innerIter; private int _currentDoc; @@ -55,37 +54,50 @@ return _currentDoc; } + /** @deprecated use {@link #nextDoc()} instead. */ + public final boolean next() throws IOException{ + return nextDoc() != NO_MORE_DOCS; + } + // @Override - public final boolean next() throws IOException{ - while (_innerIter.next()) { - int doc = _innerIter.doc(); + public int nextDoc() throws IOException { + int doc; + while ((doc = _innerIter.nextDoc()) != NO_MORE_DOCS) { if (match(doc)) { _currentDoc = doc; - return true; + return _currentDoc; } } - return false; + // TODO (3.0): set _currentDoc = NO_MORE_DOCS. + return NO_MORE_DOCS; } - + + /** @deprecated use {@link #advance(int)} instead. */ + public final boolean skipTo(int n) throws IOException{ + return advance(n) != NO_MORE_DOCS; + } + // @Override - public final boolean skipTo(int n) throws IOException{ - boolean flag = _innerIter.skipTo(n); - if (flag) { - int doc = _innerIter.doc(); + public int advance(int target) throws IOException { + // TODO (3.0): set _currentDoc = NO_MORE_DOCS where applicable and move to + // return _currentDoc at the end. + + int doc = _innerIter.advance(target); + if (doc != NO_MORE_DOCS) { if (match(doc)) { _currentDoc = doc; - return true; + return _currentDoc; } else { - while (_innerIter.next()) { - int docid = _innerIter.doc(); - if (match(docid)) { - _currentDoc = docid; - return true; + while ((doc = _innerIter.nextDoc()) != NO_MORE_DOCS) { + if (match(doc)) { + _currentDoc = doc; + return _currentDoc; } } - return false; + return NO_MORE_DOCS; } } - return flag; + return NO_MORE_DOCS; } + } Index: src/java/org/apache/lucene/search/FilteredQuery.java =================================================================== --- src/java/org/apache/lucene/search/FilteredQuery.java (revision 775940) +++ src/java/org/apache/lucene/search/FilteredQuery.java (working copy) @@ -85,7 +85,7 @@ } Filter f = FilteredQuery.this.filter; DocIdSetIterator docIdSetIterator = f.getDocIdSet(ir).iterator(); - if (docIdSetIterator.skipTo(i) && (docIdSetIterator.doc() == i)) { + if (docIdSetIterator.advance(i) == i) { return inner; } else { Explanation result = new Explanation @@ -99,36 +99,54 @@ public Query getQuery() { return FilteredQuery.this; } // return a filtering scorer - public Scorer scorer (IndexReader indexReader) throws IOException { + public Scorer scorer (IndexReader indexReader) throws IOException { final Scorer scorer = weight.scorer(indexReader); final DocIdSetIterator docIdSetIterator = filter.getDocIdSet(indexReader).iterator(); return new Scorer(similarity) { - private boolean advanceToCommon() throws IOException { - while (scorer.doc() != docIdSetIterator.doc()) { - if (scorer.doc() < docIdSetIterator.doc()) { - if (!scorer.skipTo(docIdSetIterator.doc())) { - return false; + private int advanceToCommon(int scorerDoc, int disiDoc) throws IOException { + while (scorerDoc != disiDoc) { + if (scorerDoc < disiDoc) { + if ((scorerDoc = scorer.advance(disiDoc)) == NO_MORE_DOCS) { + return NO_MORE_DOCS; } - } else if (!docIdSetIterator.skipTo(scorer.doc())) { - return false; + } else if ((disiDoc = docIdSetIterator.advance(scorerDoc)) == NO_MORE_DOCS) { + return NO_MORE_DOCS; } } - return true; + return scorerDoc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - return docIdSetIterator.next() && scorer.next() && advanceToCommon(); + return nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + // TODO (3.0): scorer.doc() should return NO_MORE_DOCS when there + // are no more docs, so maybe this method can be simplified? + int scorerDoc, disiDoc; + return (disiDoc = docIdSetIterator.nextDoc()) != NO_MORE_DOCS + && (scorerDoc = scorer.nextDoc()) != NO_MORE_DOCS + && advanceToCommon(scorerDoc, disiDoc) != NO_MORE_DOCS ? scorer.doc() : NO_MORE_DOCS; + } + public int doc() { return scorer.doc(); } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int i) throws IOException { - return docIdSetIterator.skipTo(i) - && scorer.skipTo(docIdSetIterator.doc()) - && advanceToCommon(); + return advance(i) != NO_MORE_DOCS; } + + public int advance(int target) throws IOException { + // TODO (3.0): scorer.doc() should return NO_MORE_DOCS when there + // are no more docs, so maybe this method can be simplified? + int disiDoc, scorerDoc; + return (disiDoc = docIdSetIterator.advance(target)) != NO_MORE_DOCS + && (scorerDoc = scorer.advance(disiDoc)) != NO_MORE_DOCS + && advanceToCommon(scorerDoc, disiDoc) != NO_MORE_DOCS ? scorer.doc() : NO_MORE_DOCS; + } public float score() throws IOException { return getBoost() * scorer.score(); } @@ -136,7 +154,7 @@ public Explanation explain (int i) throws IOException { Explanation exp = scorer.explain(i); - if (docIdSetIterator.skipTo(i) && (docIdSetIterator.doc() == i)) { + if (docIdSetIterator.advance(i) == i) { exp.setDescription ("allowed by filter: "+exp.getDescription()); exp.setValue(getBoost() * exp.getValue()); } else { Index: src/java/org/apache/lucene/search/IndexSearcher.java =================================================================== --- src/java/org/apache/lucene/search/IndexSearcher.java (revision 775940) +++ src/java/org/apache/lucene/search/IndexSearcher.java (working copy) @@ -236,21 +236,23 @@ DocIdSetIterator filterDocIdIterator = filter.getDocIdSet(reader).iterator(); // CHECKME: use ConjunctionScorer here? - boolean more = filterDocIdIterator.next() && scorer.skipTo(filterDocIdIterator.doc()); + int filterDoc = filterDocIdIterator.nextDoc(); + int scorerDoc = scorer.advance(filterDoc); + if (filterDoc == DocIdSetIterator.NO_MORE_DOCS + || scorerDoc == DocIdSetIterator.NO_MORE_DOCS) { + return; + } collector.setScorer(scorer); - while (more) { - int filterDocId = filterDocIdIterator.doc(); - if (filterDocId > scorer.doc() && !scorer.skipTo(filterDocId)) { - more = false; + while (true) { + if (filterDoc > scorerDoc && (scorerDoc = scorer.advance(filterDoc)) == DocIdSetIterator.NO_MORE_DOCS) { + break; + } + if (scorerDoc == filterDoc) { // permitted by filter + collector.collect(scorerDoc); + if ((filterDoc = filterDocIdIterator.nextDoc()) == DocIdSetIterator.NO_MORE_DOCS) break; } else { - int scorerDocId = scorer.doc(); - if (scorerDocId == filterDocId) { // permitted by filter - collector.collect(scorerDocId); - more = filterDocIdIterator.next(); - } else { - more = filterDocIdIterator.skipTo(scorerDocId); - } + if ((filterDoc = filterDocIdIterator.advance(scorerDoc)) == DocIdSetIterator.NO_MORE_DOCS) break; } } } Index: src/java/org/apache/lucene/search/MatchAllDocsQuery.java =================================================================== --- src/java/org/apache/lucene/search/MatchAllDocsQuery.java (revision 775940) +++ src/java/org/apache/lucene/search/MatchAllDocsQuery.java (working copy) @@ -64,10 +64,16 @@ return termDocs.doc(); } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - return termDocs.next(); + return nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + // TODO (3.0): save NO_MORE_DOCS in a member and return it in doc(). + return termDocs.next() ? termDocs.doc() : NO_MORE_DOCS; + } + public float score() { if (norms == null) { return score; @@ -76,10 +82,15 @@ } } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { - return termDocs.skipTo(target); + return advance(target) != NO_MORE_DOCS; } + public int advance(int target) throws IOException { + // TODO (3.0): save NO_MORE_DOCS in a member and return it in doc(). + return termDocs.skipTo(target) ? termDocs.doc() : NO_MORE_DOCS; + } } private class MatchAllDocsWeight implements Weight { Index: src/java/org/apache/lucene/search/NonMatchingScorer.java =================================================================== --- src/java/org/apache/lucene/search/NonMatchingScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/NonMatchingScorer.java (working copy) @@ -25,11 +25,17 @@ public int doc() { throw new UnsupportedOperationException(); } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { return false; } + + public int nextDoc() throws IOException { return NO_MORE_DOCS; } public float score() { throw new UnsupportedOperationException(); } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) { return false; } + + public int advance(int target) { return NO_MORE_DOCS; } public Explanation explain(int doc) { Explanation e = new Explanation(); Index: src/java/org/apache/lucene/search/PhraseScorer.java =================================================================== --- src/java/org/apache/lucene/search/PhraseScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/PhraseScorer.java (working copy) @@ -71,14 +71,20 @@ public int doc() { return first.doc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { + // TODO (3.0): make sure doc() will return NO_MORE_DOCS. if (firstTime) { init(); firstTime = false; } else if (more) { more = last.next(); // trigger further scanning } - return doNext(); + return doNext() ? first.doc : NO_MORE_DOCS; } // next without initial increment @@ -107,16 +113,22 @@ return norms == null ? raw : raw * Similarity.decodeNorm(norms[first.doc]); // normalize } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { + // TODO (3.0): make sure doc() returns NO_MORE_DOCS firstTime = false; for (PhrasePositions pp = first; more && pp != null; pp = pp.next) { more = pp.skipTo(target); } if (more) sort(); // re-sort - return doNext(); + return doNext() ? first.doc : NO_MORE_DOCS; } - + /** * For a document containing all the phrase query terms, compute the * frequency of the phrase in that document. @@ -163,9 +175,8 @@ public Explanation explain(final int doc) throws IOException { Explanation tfExplanation = new Explanation(); - while (next() && doc() < doc) {} - - float phraseFreq = (doc() == doc) ? freq : 0.0f; + int d = advance(doc); + float phraseFreq = (d == doc) ? freq : 0.0f; tfExplanation.setValue(getSimilarity().tf(phraseFreq)); tfExplanation.setDescription("tf(phraseFreq=" + phraseFreq + ")"); Index: src/java/org/apache/lucene/search/ReqExclScorer.java =================================================================== --- src/java/org/apache/lucene/search/ReqExclScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/ReqExclScorer.java (working copy) @@ -42,22 +42,28 @@ private boolean firstTime = true; + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { if (firstTime) { - if (! exclScorer.next()) { + if (exclScorer.nextDoc() == NO_MORE_DOCS) { exclScorer = null; // exhausted at start } firstTime = false; } if (reqScorer == null) { - return false; + return NO_MORE_DOCS; } - if (! reqScorer.next()) { + int reqDoc = reqScorer.nextDoc(); + if (reqDoc == NO_MORE_DOCS) { reqScorer = null; // exhausted, nothing left - return false; + return NO_MORE_DOCS; } if (exclScorer == null) { - return true; // reqScorer.next() already returned true + return reqDoc; } return toNonExcluded(); } @@ -73,28 +79,30 @@ * Advances reqScorer a non excluded required doc, if any. * @return true iff there is a non excluded required doc. */ - private boolean toNonExcluded() throws IOException { + private int toNonExcluded() throws IOException { int exclDoc = exclScorer.doc(); + int reqDoc = reqScorer.doc(); // may be excluded do { - int reqDoc = reqScorer.doc(); // may be excluded if (reqDoc < exclDoc) { - return true; // reqScorer advanced to before exclScorer, ie. not excluded + return reqDoc; // reqScorer advanced to before exclScorer, ie. not excluded } else if (reqDoc > exclDoc) { - if (! exclScorer.skipTo(reqDoc)) { + exclDoc = exclScorer.advance(reqDoc); + if (exclDoc == NO_MORE_DOCS) { exclScorer = null; // exhausted, no more exclusions - return true; + return reqDoc; } - exclDoc = exclScorer.doc(); if (exclDoc > reqDoc) { - return true; // not excluded + return reqDoc; // not excluded } } - } while (reqScorer.next()); + } while ((reqDoc = reqScorer.nextDoc()) != NO_MORE_DOCS); reqScorer = null; // exhausted, nothing left - return false; + return NO_MORE_DOCS; } public int doc() { + // TODO (3.0): make sure we return NO_MORE_DOCS when there are no more docs, + // and don't rely on reqScorer which may be null at this point. return reqScorer.doc(); // reqScorer may be null when next() or skipTo() already return false } @@ -106,35 +114,34 @@ return reqScorer.score(); // reqScorer may be null when next() or skipTo() already return false } - /** Skips to the first match beyond the current whose document number is - * greater than or equal to a given target. - *
When this method is used the {@link #explain(int)} method should not be used. - * @param target The target document number. - * @return true iff there is such a match. - */ + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { if (firstTime) { firstTime = false; - if (! exclScorer.skipTo(target)) { + if (exclScorer.advance(target) == NO_MORE_DOCS) { exclScorer = null; // exhausted } } if (reqScorer == null) { - return false; + return NO_MORE_DOCS; } if (exclScorer == null) { - return reqScorer.skipTo(target); + return reqScorer.advance(target); } - if (! reqScorer.skipTo(target)) { + if (reqScorer.advance(target) == NO_MORE_DOCS) { reqScorer = null; - return false; + return NO_MORE_DOCS; } return toNonExcluded(); } - + public Explanation explain(int doc) throws IOException { Explanation res = new Explanation(); - if (exclScorer.skipTo(doc) && (exclScorer.doc() == doc)) { + if (exclScorer.advance(doc) == doc) { res.setDescription("excluded"); } else { res.setDescription("not excluded"); Index: src/java/org/apache/lucene/search/ReqOptSumScorer.java =================================================================== --- src/java/org/apache/lucene/search/ReqOptSumScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/ReqOptSumScorer.java (working copy) @@ -45,14 +45,24 @@ private boolean firstTimeOptScorer = true; + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { return reqScorer.next(); } + public int nextDoc() throws IOException { + return reqScorer.nextDoc(); + } + + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { return reqScorer.skipTo(target); } + public int advance(int target) throws IOException { + return reqScorer.advance(target); + } + public int doc() { return reqScorer.doc(); } @@ -67,20 +77,18 @@ float reqScore = reqScorer.score(); if (firstTimeOptScorer) { firstTimeOptScorer = false; - if (! optScorer.skipTo(curDoc)) { + if (optScorer.advance(curDoc) == NO_MORE_DOCS) { optScorer = null; return reqScore; } } else if (optScorer == null) { return reqScore; - } else if ((optScorer.doc() < curDoc) && (! optScorer.skipTo(curDoc))) { + } else if (optScorer.doc() < curDoc && optScorer.advance(curDoc) == NO_MORE_DOCS) { optScorer = null; return reqScore; } // assert (optScorer != null) && (optScorer.doc() >= curDoc); - return (optScorer.doc() == curDoc) - ? reqScore + optScorer.score() - : reqScore; + return optScorer.doc() == curDoc ? reqScore + optScorer.score() : reqScore; } /** Explain the score of a document. Index: src/java/org/apache/lucene/search/ScoreCachingWrappingScorer.java =================================================================== --- src/java/org/apache/lucene/search/ScoreCachingWrappingScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/ScoreCachingWrappingScorer.java (working copy) @@ -68,16 +68,26 @@ return scorer.doc(); } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { return scorer.next(); } + public int nextDoc() throws IOException { + return scorer.nextDoc(); + } + public void score(Collector collector) throws IOException { scorer.score(collector); } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { return scorer.skipTo(target); } + public int advance(int target) throws IOException { + return scorer.advance(target); + } + } Index: src/java/org/apache/lucene/search/Scorer.java =================================================================== --- src/java/org/apache/lucene/search/Scorer.java (revision 775940) +++ src/java/org/apache/lucene/search/Scorer.java (working copy) @@ -64,8 +64,9 @@ */ public void score(Collector collector) throws IOException { collector.setScorer(this); - while (next()) { - collector.collect(doc()); + int doc; + while ((doc = nextDoc()) != NO_MORE_DOCS) { + collector.collect(doc); } } @@ -91,12 +92,12 @@ */ protected boolean score(Collector collector, int max) throws IOException { collector.setScorer(this); - while (doc() < max) { - collector.collect(doc()); - if (!next()) - return false; + int doc = doc(); + while (doc < max) { + collector.collect(doc); + doc = nextDoc(); } - return true; + return doc == NO_MORE_DOCS; } /** Returns the score of the current document matching the query. Index: src/java/org/apache/lucene/search/TermScorer.java =================================================================== --- src/java/org/apache/lucene/search/TermScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/TermScorer.java (working copy) @@ -65,7 +65,7 @@ } public void score(Collector c) throws IOException { - next(); + nextDoc(); score(c, Integer.MAX_VALUE); } @@ -99,12 +99,26 @@ */ public int doc() { return doc; } - /** Advances to the next document matching the query. - *
The iterator over the matching documents is buffered using + /** + * Advances to the next document matching the query.
+ * The iterator over the matching documents is buffered using * {@link TermDocs#read(int[],int[])}. + * * @return true iff there is another document matching the query. + * @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + /** + * Advances to the next document matching the query.
+ * The iterator over the matching documents is buffered using + * {@link TermDocs#read(int[],int[])}. + * + * @return the document matching the query or -1 if there are no more documents. + */ + public int nextDoc() throws IOException { pointer++; if (pointer >= pointerMax) { pointerMax = termDocs.read(docs, freqs); // refill buffer @@ -112,14 +126,14 @@ pointer = 0; } else { termDocs.close(); // close stream - doc = Integer.MAX_VALUE; // set to sentinel value - return false; + doc = NO_MORE_DOCS; // set to sentinel value + return NO_MORE_DOCS; } } doc = docs[pointer]; - return true; + return doc; } - + public float score() { int f = freqs[pointer]; float raw = // compute tf(f)*weight @@ -130,18 +144,35 @@ return norms == null ? raw : raw * SIM_NORM_DECODER[norms[doc] & 0xFF]; // normalize for field } - /** Skips to the first match beyond the current whose document number is - * greater than or equal to a given target. - *
The implementation uses {@link TermDocs#skipTo(int)}. - * @param target The target document number. + /** + * Skips to the first match beyond the current whose document number is + * greater than or equal to a given target.
+ * The implementation uses {@link TermDocs#skipTo(int)}. + * + * @param target + * The target document number. * @return true iff there is such a match. + * @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + /** + * Advances to the first match beyond the current whose document number is + * greater than or equal to a given target.
+ * The implementation uses {@link TermDocs#skipTo(int)}. + * + * @param target + * The target document number. + * @return the matching document or -1 if none exist. + */ + public int advance(int target) throws IOException { // first scan in cache for (pointer++; pointer < pointerMax; pointer++) { if (docs[pointer] >= target) { doc = docs[pointer]; - return true; + return doc; } } @@ -153,11 +184,11 @@ docs[pointer] = doc = termDocs.doc(); freqs[pointer] = termDocs.freq(); } else { - doc = Integer.MAX_VALUE; + doc = NO_MORE_DOCS; } - return result; + return doc; } - + /** Returns an explanation of the score for a document. *
When this method is used, the {@link #next()} method * and the {@link #score(HitCollector)} method should not be used. Index: src/java/org/apache/lucene/search/function/CustomScoreQuery.java =================================================================== --- src/java/org/apache/lucene/search/function/CustomScoreQuery.java (revision 775940) +++ src/java/org/apache/lucene/search/function/CustomScoreQuery.java (working copy) @@ -367,17 +367,21 @@ this.vScores = new float[valSrcScorers.length]; } - /*(non-Javadoc) @see org.apache.lucene.search.Scorer#next() */ + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - boolean hasNext = subQueryScorer.next(); - if (hasNext) { - for(int i = 0; i < valSrcScorers.length; i++) { - valSrcScorers[i].skipTo(subQueryScorer.doc()); + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { + int doc = subQueryScorer.nextDoc(); + if (doc != NO_MORE_DOCS) { + for (int i = 0; i < valSrcScorers.length; i++) { + valSrcScorers[i].advance(doc); } } - return hasNext; + return doc; } - + /*(non-Javadoc) @see org.apache.lucene.search.Scorer#doc() */ public int doc() { return subQueryScorer.doc(); @@ -391,17 +395,21 @@ return qWeight * customScore(subQueryScorer.doc(), subQueryScorer.score(), vScores); } - /*(non-Javadoc) @see org.apache.lucene.search.Scorer#skipTo(int) */ + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { - boolean hasNext = subQueryScorer.skipTo(target); - if (hasNext) { - for (int i = 0; i < valSrcScorers.length; i++) { - valSrcScorers[i].skipTo(subQueryScorer.doc()); + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { + int doc = subQueryScorer.advance(target); + if (doc != NO_MORE_DOCS) { + for (int i = 0; i < valSrcScorers.length; i++) { + valSrcScorers[i].advance(doc); } } - return hasNext; + return doc; } - + /*(non-Javadoc) @see org.apache.lucene.search.Scorer#explain(int) */ public Explanation explain(int doc) throws IOException { Explanation subQueryExpl = weight.subQueryWeight.explain(reader,doc); Index: src/java/org/apache/lucene/search/function/ValueSourceQuery.java =================================================================== --- src/java/org/apache/lucene/search/function/ValueSourceQuery.java (revision 775940) +++ src/java/org/apache/lucene/search/function/ValueSourceQuery.java (working copy) @@ -126,13 +126,16 @@ termDocs = reader.termDocs(null); } - /*(non-Javadoc) @see org.apache.lucene.search.Scorer#next() */ + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { return termDocs.next(); } - /*(non-Javadoc) @see org.apache.lucene.search.Scorer#doc() - */ + public int nextDoc() throws IOException { + return termDocs.next() ? termDocs.doc() : NO_MORE_DOCS; + } + + // TODO (3.0): make sure to return NO_MORE_DOCS public int doc() { return termDocs.doc(); } @@ -142,10 +145,14 @@ return qWeight * vals.floatVal(termDocs.doc()); } - /*(non-Javadoc) @see org.apache.lucene.search.Scorer#skipTo(int) */ + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { return termDocs.skipTo(target); } + + public int advance(int target) throws IOException { + return termDocs.skipTo(target) ? termDocs.doc() : NO_MORE_DOCS; + } /*(non-Javadoc) @see org.apache.lucene.search.Scorer#explain(int) */ public Explanation explain(int doc) throws IOException { Index: src/java/org/apache/lucene/search/payloads/BoostingTermQuery.java =================================================================== --- src/java/org/apache/lucene/search/payloads/BoostingTermQuery.java (revision 775940) +++ src/java/org/apache/lucene/search/payloads/BoostingTermQuery.java (working copy) @@ -81,9 +81,9 @@ } - protected boolean setFreqCurrentDoc() throws IOException { + protected int setFreqCurrentDoc() throws IOException { if (!more) { - return false; + return NO_MORE_DOCS; } doc = spans.doc(); freq = 0.0f; @@ -98,7 +98,7 @@ more = spans.next();//this moves positions to the next match in this document } - return more || (freq != 0); + return more || freq != 0 ? doc : NO_MORE_DOCS; } Index: src/java/org/apache/lucene/search/spans/SpanScorer.java =================================================================== --- src/java/org/apache/lucene/search/spans/SpanScorer.java (revision 775940) +++ src/java/org/apache/lucene/search/spans/SpanScorer.java (working copy) @@ -49,7 +49,12 @@ doc = -1; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() throws IOException { if (firstTime) { more = spans.next(); firstTime = false; @@ -57,23 +62,28 @@ return setFreqCurrentDoc(); } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { if (firstTime) { more = spans.skipTo(target); firstTime = false; } - if (! more) { - return false; + if (!more) { + return NO_MORE_DOCS; } if (spans.doc() < target) { // setFreqCurrentDoc() leaves spans.doc() ahead more = spans.skipTo(target); } return setFreqCurrentDoc(); } - - protected boolean setFreqCurrentDoc() throws IOException { - if (! more) { - return false; + + protected int setFreqCurrentDoc() throws IOException { + if (!more) { + return NO_MORE_DOCS; } doc = spans.doc(); freq = 0.0f; @@ -82,9 +92,10 @@ freq += getSimilarity().sloppyFreq(matchLength); more = spans.next(); } while (more && (doc == spans.doc())); - return true; + return doc; } + // TODO (3.0): make sure to return NO_MORE_DOCS. public int doc() { return doc; } public float score() throws IOException { @@ -95,9 +106,9 @@ public Explanation explain(final int doc) throws IOException { Explanation tfExplanation = new Explanation(); - skipTo(doc); + int expDoc = advance(doc); - float phraseFreq = (doc() == doc) ? freq : 0.0f; + float phraseFreq = (expDoc == doc) ? freq : 0.0f; tfExplanation.setValue(getSimilarity().tf(phraseFreq)); tfExplanation.setDescription("tf(phraseFreq=" + phraseFreq + ")"); Index: src/java/org/apache/lucene/util/DocIdBitSet.java =================================================================== --- src/java/org/apache/lucene/util/DocIdBitSet.java (revision 775940) +++ src/java/org/apache/lucene/util/DocIdBitSet.java (working copy) @@ -18,6 +18,7 @@ */ import java.util.BitSet; + import org.apache.lucene.search.DocIdSet; import org.apache.lucene.search.DocIdSetIterator; @@ -55,23 +56,30 @@ return docId; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() { // (docId + 1) on next line requires -1 initial value for docNr: - return checkNextDocId(bitSet.nextSetBit(docId + 1)); + return nextDoc() != NO_MORE_DOCS; } + + public int nextDoc() { + // (docId + 1) on next line requires -1 initial value for docNr: + int d = bitSet.nextSetBit(docId + 1); + // -1 returned by BitSet.nextSetBit() when exhausted + docId = d == -1 ? NO_MORE_DOCS : d; + return docId; + } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int skipDocNr) { - return checkNextDocId( bitSet.nextSetBit(skipDocNr)); + return advance(skipDocNr) != NO_MORE_DOCS; } - private boolean checkNextDocId(int d) { - if (d == -1) { // -1 returned by BitSet.nextSetBit() when exhausted - docId = Integer.MAX_VALUE; - return false; - } else { - docId = d; - return true; - } + public int advance(int target) { + int d = bitSet.nextSetBit(target); + // -1 returned by BitSet.nextSetBit() when exhausted + docId = d == -1 ? NO_MORE_DOCS : d; + return docId; } } } Index: src/java/org/apache/lucene/util/OpenBitSetDISI.java =================================================================== --- src/java/org/apache/lucene/util/OpenBitSetDISI.java (revision 775940) +++ src/java/org/apache/lucene/util/OpenBitSetDISI.java (working copy) @@ -47,8 +47,10 @@ * constructor. */ public void inPlaceOr(DocIdSetIterator disi) throws IOException { - while (disi.next() && (disi.doc() < size())) { - fastSet(disi.doc()); + int doc; + long size = size(); + while ((doc = disi.nextDoc()) < size) { + fastSet(doc); } } @@ -60,8 +62,8 @@ */ public void inPlaceAnd(DocIdSetIterator disi) throws IOException { int bitSetDoc = nextSetBit(0); - while ((bitSetDoc != -1) && disi.skipTo(bitSetDoc)) { - int disiDoc = disi.doc(); + int disiDoc; + while (bitSetDoc != -1 && (disiDoc = disi.advance(bitSetDoc)) != DocIdSetIterator.NO_MORE_DOCS) { clear(bitSetDoc, disiDoc); bitSetDoc = nextSetBit(disiDoc + 1); } @@ -77,8 +79,10 @@ * constructor. */ public void inPlaceNot(DocIdSetIterator disi) throws IOException { - while (disi.next() && (disi.doc() < size())) { - fastClear(disi.doc()); + int doc; + long size = size(); + while ((doc = disi.nextDoc()) < size) { + fastClear(doc); } } @@ -89,8 +93,10 @@ * constructor. */ public void inPlaceXor(DocIdSetIterator disi) throws IOException { - while (disi.next() && (disi.doc() < size())) { - fastFlip(disi.doc()); + int doc; + long size = size(); + while ((doc = disi.nextDoc()) < size) { + fastFlip(doc); } } } Index: src/java/org/apache/lucene/util/OpenBitSetIterator.java =================================================================== --- src/java/org/apache/lucene/util/OpenBitSetIterator.java (revision 775940) +++ src/java/org/apache/lucene/util/OpenBitSetIterator.java (working copy) @@ -17,8 +17,6 @@ package org.apache.lucene.util; -import java.io.IOException; - import org.apache.lucene.search.DocIdSetIterator; /** An iterator to iterate over set bits in an OpenBitSet. @@ -35,7 +33,34 @@ // should be faster than accessing an array for each index, and // the total array size is kept smaller (256*sizeof(int))=1K protected final static int[] bitlist={ - 0x0,0x1,0x2,0x21,0x3,0x31,0x32,0x321,0x4,0x41,0x42,0x421,0x43,0x431,0x432,0x4321,0x5,0x51,0x52,0x521,0x53,0x531,0x532,0x5321,0x54,0x541,0x542,0x5421,0x543,0x5431,0x5432,0x54321,0x6,0x61,0x62,0x621,0x63,0x631,0x632,0x6321,0x64,0x641,0x642,0x6421,0x643,0x6431,0x6432,0x64321,0x65,0x651,0x652,0x6521,0x653,0x6531,0x6532,0x65321,0x654,0x6541,0x6542,0x65421,0x6543,0x65431,0x65432,0x654321,0x7,0x71,0x72,0x721,0x73,0x731,0x732,0x7321,0x74,0x741,0x742,0x7421,0x743,0x7431,0x7432,0x74321,0x75,0x751,0x752,0x7521,0x753,0x7531,0x7532,0x75321,0x754,0x7541,0x7542,0x75421,0x7543,0x75431,0x75432,0x754321,0x76,0x761,0x762,0x7621,0x763,0x7631,0x7632,0x76321,0x764,0x7641,0x7642,0x76421,0x7643,0x76431,0x76432,0x764321,0x765,0x7651,0x7652,0x76521,0x7653,0x76531,0x76532,0x765321,0x7654,0x76541,0x76542,0x765421,0x76543,0x765431,0x765432,0x7654321,0x8,0x81,0x82,0x821,0x83,0x831,0x832,0x8321,0x84,0x841,0x842,0x8421,0x843,0x8431,0x8432,0x84321,0x85,0x851,0x852,0x8521,0x853,0x8531,0x8532,0x85321,0x854,0x8541,0x8542,0x85421,0x8543,0x85431,0x85432,0x854321,0x86,0x861,0x862,0x8621,0x863,0x8631,0x8632,0x86321,0x864,0x8641,0x8642,0x86421,0x8643,0x86431,0x86432,0x864321,0x865,0x8651,0x8652,0x86521,0x8653,0x86531,0x86532,0x865321,0x8654,0x86541,0x86542,0x865421,0x86543,0x865431,0x865432,0x8654321,0x87,0x871,0x872,0x8721,0x873,0x8731,0x8732,0x87321,0x874,0x8741,0x8742,0x87421,0x8743,0x87431,0x87432,0x874321,0x875,0x8751,0x8752,0x87521,0x8753,0x87531,0x87532,0x875321,0x8754,0x87541,0x87542,0x875421,0x87543,0x875431,0x875432,0x8754321,0x876,0x8761,0x8762,0x87621,0x8763,0x87631,0x87632,0x876321,0x8764,0x87641,0x87642,0x876421,0x87643,0x876431,0x876432,0x8764321,0x8765,0x87651,0x87652,0x876521,0x87653,0x876531,0x876532,0x8765321,0x87654,0x876541,0x876542,0x8765421,0x876543,0x8765431,0x8765432,0x87654321 + 0x0, 0x1, 0x2, 0x21, 0x3, 0x31, 0x32, 0x321, 0x4, 0x41, 0x42, 0x421, 0x43, + 0x431, 0x432, 0x4321, 0x5, 0x51, 0x52, 0x521, 0x53, 0x531, 0x532, 0x5321, + 0x54, 0x541, 0x542, 0x5421, 0x543, 0x5431, 0x5432, 0x54321, 0x6, 0x61, 0x62, + 0x621, 0x63, 0x631, 0x632, 0x6321, 0x64, 0x641, 0x642, 0x6421, 0x643, + 0x6431, 0x6432, 0x64321, 0x65, 0x651, 0x652, 0x6521, 0x653, 0x6531, 0x6532, + 0x65321, 0x654, 0x6541, 0x6542, 0x65421, 0x6543, 0x65431, 0x65432, 0x654321, + 0x7, 0x71, 0x72, 0x721, 0x73, 0x731, 0x732, 0x7321, 0x74, 0x741, 0x742, + 0x7421, 0x743, 0x7431, 0x7432, 0x74321, 0x75, 0x751, 0x752, 0x7521, 0x753, + 0x7531, 0x7532, 0x75321, 0x754, 0x7541, 0x7542, 0x75421, 0x7543, 0x75431, + 0x75432, 0x754321, 0x76, 0x761, 0x762, 0x7621, 0x763, 0x7631, 0x7632, + 0x76321, 0x764, 0x7641, 0x7642, 0x76421, 0x7643, 0x76431, 0x76432, 0x764321, + 0x765, 0x7651, 0x7652, 0x76521, 0x7653, 0x76531, 0x76532, 0x765321, 0x7654, + 0x76541, 0x76542, 0x765421, 0x76543, 0x765431, 0x765432, 0x7654321, 0x8, + 0x81, 0x82, 0x821, 0x83, 0x831, 0x832, 0x8321, 0x84, 0x841, 0x842, 0x8421, + 0x843, 0x8431, 0x8432, 0x84321, 0x85, 0x851, 0x852, 0x8521, 0x853, 0x8531, + 0x8532, 0x85321, 0x854, 0x8541, 0x8542, 0x85421, 0x8543, 0x85431, 0x85432, + 0x854321, 0x86, 0x861, 0x862, 0x8621, 0x863, 0x8631, 0x8632, 0x86321, 0x864, + 0x8641, 0x8642, 0x86421, 0x8643, 0x86431, 0x86432, 0x864321, 0x865, 0x8651, + 0x8652, 0x86521, 0x8653, 0x86531, 0x86532, 0x865321, 0x8654, 0x86541, + 0x86542, 0x865421, 0x86543, 0x865431, 0x865432, 0x8654321, 0x87, 0x871, + 0x872, 0x8721, 0x873, 0x8731, 0x8732, 0x87321, 0x874, 0x8741, 0x8742, + 0x87421, 0x8743, 0x87431, 0x87432, 0x874321, 0x875, 0x8751, 0x8752, 0x87521, + 0x8753, 0x87531, 0x87532, 0x875321, 0x8754, 0x87541, 0x87542, 0x875421, + 0x87543, 0x875431, 0x875432, 0x8754321, 0x876, 0x8761, 0x8762, 0x87621, + 0x8763, 0x87631, 0x87632, 0x876321, 0x8764, 0x87641, 0x87642, 0x876421, + 0x87643, 0x876431, 0x876432, 0x8764321, 0x8765, 0x87651, 0x87652, 0x876521, + 0x87653, 0x876531, 0x876532, 0x8765321, 0x87654, 0x876541, 0x876542, + 0x8765421, 0x876543, 0x8765431, 0x8765432, 0x87654321 }; /***** the python code that generated bitlist def bits2int(val): @@ -104,50 +129,26 @@ } ******/ + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() { - if (indexArray==0) { - if (word!=0) { - word >>>= 8; - wordShift += 8; - } - - while (word==0) { - if (++i >= words) { - curDocId = -1; - return false; - } - word = arr[i]; - wordShift =-1; // loop invariant code motion should move this - } - - // after the first time, should I go with a linear search, or - // stick with the binary search in shift? - shift(); - } - - int bitIndex = (indexArray & 0x0f) + wordShift; - indexArray >>>= 4; - // should i<<6 be cached as a separate variable? - // it would only save one cycle in the best circumstances. - curDocId = (i<<6) + bitIndex; - return true; + return nextDoc() != NO_MORE_DOCS; } - /** Moves iterator to the next doc and returns its id; - returns -1 when this iterator is exhausted. */ public int nextDoc() { - if (indexArray==0) { - if (word!=0) { + if (indexArray == 0) { + if (word != 0) { word >>>= 8; wordShift += 8; } - while (word==0) { + while (word == 0) { if (++i >= words) { - return curDocId = -1; + // TODO (3.0): change to NO_MORE_DOCS + curDocId = -1; + return NO_MORE_DOCS; } word = arr[i]; - wordShift =-1; // loop invariant code motion should move this + wordShift = -1; // loop invariant code motion should move this } // after the first time, should I go with a linear search, or @@ -162,27 +163,34 @@ return curDocId = (i<<6) + bitIndex; } + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) { - indexArray=0; + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) { + indexArray = 0; i = target >> 6; - if (i>=words) { - word =0; // setup so next() will also return -1 + if (i >= words) { + word = 0; // setup so next() will also return -1 + // TODO (3.0): change to NO_MORE_DOCS curDocId = -1; - return false; + return NO_MORE_DOCS; } wordShift = target & 0x3f; word = arr[i] >>> wordShift; - if (word !=0) { + if (word != 0) { wordShift--; // compensate for 1 based arrIndex } else { - while (word ==0) { + while (word == 0) { if (++i >= words) { + // TODO (3.0): change to NO_MORE_DOCS curDocId = -1; - return false; + return NO_MORE_DOCS; } word = arr[i]; } - wordShift =-1; + wordShift = -1; } shift(); @@ -191,42 +199,9 @@ indexArray >>>= 4; // should i<<6 be cached as a separate variable? // it would only save one cycle in the best circumstances. - curDocId = (i<<6) + bitIndex; - return true; - } - - /** Behaves like {@link #skipTo(int)} and returns the docId the iterator - * skipped to; returns -1 if no valid document could be skipped to. */ - public int next(int fromIndex) { - indexArray=0; - i = fromIndex >> 6; - if (i>=words) { - word =0; // setup so next() will also return -1 - return curDocId = -1; - } - wordShift = fromIndex & 0x3f; - word = arr[i] >>> wordShift; - if (word !=0) { - wordShift--; // compensate for 1 based arrIndex - } else { - while (word ==0) { - if (++i >= words) { - return curDocId = -1; - } - word = arr[i]; - } - wordShift =-1; - } - - shift(); - - int bitIndex = (indexArray & 0x0f) + wordShift; - indexArray >>>= 4; - // should i<<6 be cached as a separate variable? - // it would only save one cycle in the best circumstances. return curDocId = (i<<6) + bitIndex; } - + public int doc() { return this.curDocId; } Index: src/java/org/apache/lucene/util/ScorerDocQueue.java =================================================================== --- src/java/org/apache/lucene/util/ScorerDocQueue.java (revision 775940) +++ src/java/org/apache/lucene/util/ScorerDocQueue.java (working copy) @@ -20,6 +20,8 @@ /* Derived from org.apache.lucene.util.PriorityQueue of March 2005 */ import java.io.IOException; + +import org.apache.lucene.search.DocIdSetIterator; import org.apache.lucene.search.Scorer; /** A ScorerDocQueue maintains a partial ordering of its Scorers such that the @@ -113,11 +115,11 @@ } public final boolean topNextAndAdjustElsePop() throws IOException { - return checkAdjustElsePop( topHSD.scorer.next()); + return checkAdjustElsePop(topHSD.scorer.nextDoc() != DocIdSetIterator.NO_MORE_DOCS); } public final boolean topSkipToAndAdjustElsePop(int target) throws IOException { - return checkAdjustElsePop( topHSD.scorer.skipTo(target)); + return checkAdjustElsePop(topHSD.scorer.advance(target) != DocIdSetIterator.NO_MORE_DOCS); } private boolean checkAdjustElsePop(boolean cond) { Index: src/java/org/apache/lucene/util/SortedVIntList.java =================================================================== --- src/java/org/apache/lucene/util/SortedVIntList.java (revision 775940) +++ src/java/org/apache/lucene/util/SortedVIntList.java (working copy) @@ -24,10 +24,15 @@ import org.apache.lucene.search.DocIdSetIterator; /** - * Store and iterate sorted integers in compressed form in RAM. - *
The code for compressing the differences between ascending integers was - * borrowed from {@link org.apache.lucene.store.IndexInput} and - * {@link org.apache.lucene.store.IndexOutput}. + * Stores and iterate on sorted integers in compressed form in RAM.
+ * The code for compressing the differences between ascending integers was + * borrowed from {@link org.apache.lucene.store.IndexInput} and + * {@link org.apache.lucene.store.IndexOutput}. + *

+ * NOTE: this class assumes the stored integers are doc Ids (hence why it + * extends {@link DocIdSet}). Therefore its {@link #iterator()} assumes {@value + * DocIdSetIterator#NO_MORE_DOCS} can be used as sentinel. If you intent to use + * this value, then make sure it's not used during search flow. */ public class SortedVIntList extends DocIdSet { /** When a BitSet has fewer than 1 in BITS2VINTLIST_SIZE bits set, @@ -99,8 +104,9 @@ */ public SortedVIntList(DocIdSetIterator docIdSetIterator) throws IOException { SortedVIntListBuilder builder = new SortedVIntListBuilder(); - while (docIdSetIterator.next()) { - builder.addInt(docIdSetIterator.doc()); + int doc; + while ((doc = docIdSetIterator.nextDoc()) != DocIdSetIterator.NO_MORE_DOCS) { + builder.addInt(doc); } builder.done(); } @@ -192,26 +198,38 @@ } } + // TODO (3.0): make sure to return NO_MORE_DOCS public int doc() {return lastInt;} + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() { + return nextDoc() != NO_MORE_DOCS; + } + + public int nextDoc() { if (bytePos >= lastBytePos) { - return false; + return NO_MORE_DOCS; } else { advance(); - return true; + return lastInt; } } - + + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int docNr) { + return advance(docNr) != NO_MORE_DOCS; + } + + public int advance(int target) { while (bytePos < lastBytePos) { advance(); - if (lastInt >= docNr) { // No skipping to docNr available. - return true; + if (lastInt >= target) { + return lastInt; } } - return false; + return NO_MORE_DOCS; } + }; } } Index: src/test/org/apache/lucene/search/JustCompileSearch.java =================================================================== --- src/test/org/apache/lucene/search/JustCompileSearch.java (revision 775940) +++ src/test/org/apache/lucene/search/JustCompileSearch.java (working copy) @@ -179,14 +179,23 @@ throw new UnsupportedOperationException(UNSUPPORTED_MSG); } + /** @deprecated delete in 3.0 */ public boolean next() throws IOException { throw new UnsupportedOperationException(UNSUPPORTED_MSG); } + /** @deprecated delete in 3.0 */ public boolean skipTo(int target) throws IOException { throw new UnsupportedOperationException(UNSUPPORTED_MSG); } + public int nextDoc() throws IOException { + throw new UnsupportedOperationException(UNSUPPORTED_MSG); + } + + public int advance(int target) throws IOException { + throw new UnsupportedOperationException(UNSUPPORTED_MSG); + } } static final class JustCompileFieldCache implements FieldCache { @@ -482,14 +491,23 @@ throw new UnsupportedOperationException(UNSUPPORTED_MSG); } + /** @deprecated delete in 3.0. */ public boolean next() throws IOException { throw new UnsupportedOperationException(UNSUPPORTED_MSG); } + /** @deprecated delete in 3.0. */ public boolean skipTo(int target) throws IOException { throw new UnsupportedOperationException(UNSUPPORTED_MSG); } + + public int nextDoc() throws IOException { + throw new UnsupportedOperationException(UNSUPPORTED_MSG); + } + public int advance(int target) throws IOException { + throw new UnsupportedOperationException(UNSUPPORTED_MSG); + } } static final class JustCompileSimilarity extends Similarity { Index: src/test/org/apache/lucene/search/QueryUtils.java =================================================================== --- src/test/org/apache/lucene/search/QueryUtils.java (revision 775940) +++ src/test/org/apache/lucene/search/QueryUtils.java (working copy) @@ -1,13 +1,13 @@ package org.apache.lucene.search; -import junit.framework.TestCase; - import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.io.ObjectInputStream; import java.io.ObjectOutputStream; +import junit.framework.Assert; + import org.apache.lucene.index.IndexReader; /** @@ -56,17 +56,17 @@ } public static void checkEqual(Query q1, Query q2) { - TestCase.assertEquals(q1, q2); - TestCase.assertEquals(q1.hashCode(), q2.hashCode()); + Assert.assertEquals(q1, q2); + Assert.assertEquals(q1.hashCode(), q2.hashCode()); } public static void checkUnequal(Query q1, Query q2) { - TestCase.assertTrue(!q1.equals(q2)); - TestCase.assertTrue(!q2.equals(q1)); + Assert.assertTrue(!q1.equals(q2)); + Assert.assertTrue(!q2.equals(q1)); // possible this test can fail on a hash collision... if that // happens, please change test to use a different example. - TestCase.assertTrue(q1.hashCode() != q2.hashCode()); + Assert.assertTrue(q1.hashCode() != q2.hashCode()); } /** deep check that explanations of a query 'score' correctly */ @@ -169,7 +169,8 @@ try { int op = order[(opidx[0]++)%order.length]; //System.out.println(op==skip_op ? "skip("+(sdoc[0]+1)+")":"next()"); - boolean more = op==skip_op ? scorer.skipTo(sdoc[0]+1) : scorer.next(); + boolean more = op == skip_op ? scorer.advance(sdoc[0] + 1) != DocIdSetIterator.NO_MORE_DOCS + : scorer.nextDoc() != DocIdSetIterator.NO_MORE_DOCS; sdoc[0] = scorer.doc(); float scorerScore = scorer.score(); float scorerScore2 = scorer.score(); @@ -204,8 +205,9 @@ // make sure next call to scorer is false. int op = order[(opidx[0]++)%order.length]; //System.out.println(op==skip_op ? "last: skip()":"last: next()"); - boolean more = op==skip_op ? scorer.skipTo(sdoc[0]+1) : scorer.next(); - TestCase.assertFalse(more); + boolean more = (op == skip_op ? scorer.advance(sdoc[0] + 1) : scorer + .nextDoc()) != DocIdSetIterator.NO_MORE_DOCS; + Assert.assertFalse(more); } } @@ -228,11 +230,11 @@ for (int i=lastDoc[0]+1; i<=doc; i++) { Weight w = q.weight(s); Scorer scorer = w.scorer(s.getIndexReader()); - TestCase.assertTrue("query collected "+doc+" but skipTo("+i+") says no more docs!",scorer.skipTo(i)); - TestCase.assertEquals("query collected "+doc+" but skipTo("+i+") got to "+scorer.doc(),doc,scorer.doc()); + Assert.assertTrue("query collected "+doc+" but skipTo("+i+") says no more docs!",scorer.advance(i) != DocIdSetIterator.NO_MORE_DOCS); + Assert.assertEquals("query collected "+doc+" but skipTo("+i+") got to "+scorer.doc(),doc,scorer.doc()); float skipToScore = scorer.score(); - TestCase.assertEquals("unstable skipTo("+i+") score!",skipToScore,scorer.score(),maxDiff); - TestCase.assertEquals("query assigned doc "+doc+" a score of <"+score+"> but skipTo("+i+") has <"+skipToScore+">!",score,skipToScore,maxDiff); + Assert.assertEquals("unstable skipTo("+i+") score!",skipToScore,scorer.score(),maxDiff); + Assert.assertEquals("query assigned doc "+doc+" a score of <"+score+"> but skipTo("+i+") has <"+skipToScore+">!",score,skipToScore,maxDiff); } lastDoc[0] = doc; } catch (IOException e) { @@ -245,8 +247,8 @@ }); Weight w = q.weight(s); Scorer scorer = w.scorer(s.getIndexReader()); - boolean more = scorer.skipTo(lastDoc[0]+1); + boolean more = scorer.advance(lastDoc[0] + 1) != DocIdSetIterator.NO_MORE_DOCS; if (more) - TestCase.assertFalse("query's last doc was "+lastDoc[0]+" but skipTo("+(lastDoc[0]+1)+") got to "+scorer.doc(),more); + Assert.assertFalse("query's last doc was "+lastDoc[0]+" but skipTo("+(lastDoc[0]+1)+") got to "+scorer.doc(),more); } } Index: src/test/org/apache/lucene/search/TestDisjunctionMaxQuery.java =================================================================== --- src/test/org/apache/lucene/search/TestDisjunctionMaxQuery.java (revision 775940) +++ src/test/org/apache/lucene/search/TestDisjunctionMaxQuery.java (working copy) @@ -136,7 +136,7 @@ final Weight dw = dq.weight(s); final Scorer ds = dw.scorer(r); - final boolean skipOk = ds.skipTo(3); + final boolean skipOk = ds.advance(3) != DocIdSetIterator.NO_MORE_DOCS; if (skipOk) { fail("firsttime skipTo found a match? ... " + r.document(ds.doc()).get("id")); @@ -152,7 +152,7 @@ final Weight dw = dq.weight(s); final Scorer ds = dw.scorer(r); - assertTrue("firsttime skipTo found no match", ds.skipTo(3)); + assertTrue("firsttime skipTo found no match", ds.advance(3) != DocIdSetIterator.NO_MORE_DOCS); assertEquals("found wrong docid", "d4", r.document(ds.doc()).get("id")); } Index: src/test/org/apache/lucene/search/TestDocIdSet.java =================================================================== --- src/test/org/apache/lucene/search/TestDocIdSet.java (revision 775940) +++ src/test/org/apache/lucene/search/TestDocIdSet.java (working copy) @@ -34,27 +34,38 @@ public DocIdSetIterator iterator() { return new DocIdSetIterator() { - int docid=-1; + int docid = -1; + //@Override + // TODO (3.0): make sure to return NO_MORE_DOCS public int doc() { return docid; } + /** @deprecated use {@link #nextDoc()} instead. */ + public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; + } + //@Override - public boolean next() throws IOException { + public int nextDoc() throws IOException { docid++; - return (docid doc()); - - return true; + } + return docid; } }; } @@ -70,10 +81,11 @@ DocIdSetIterator iter = filteredSet.iterator(); ArrayList/**/ list = new ArrayList/**/(); - if (iter.skipTo(3)) { - list.add(new Integer(iter.doc())); - while(iter.next()) { - list.add(new Integer(iter.doc())); + int doc = iter.advance(3); + if (doc != DocIdSetIterator.NO_MORE_DOCS) { + list.add(Integer.valueOf(doc)); + while((doc = iter.nextDoc()) != DocIdSetIterator.NO_MORE_DOCS) { + list.add(Integer.valueOf(doc)); } } Index: src/test/org/apache/lucene/search/TestPositiveScoresOnlyCollector.java =================================================================== --- src/test/org/apache/lucene/search/TestPositiveScoresOnlyCollector.java (revision 775940) +++ src/test/org/apache/lucene/search/TestPositiveScoresOnlyCollector.java (working copy) @@ -38,13 +38,23 @@ public int doc() { return idx; } - public boolean next() throws IOException { - return ++idx == scores.length; + /** @deprecated use {@link #nextDoc()} instead. */ + public boolean next() throws IOException { + return nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + return ++idx != scores.length ? idx : NO_MORE_DOCS; + } + + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { idx = target; - return idx >= scores.length; + return idx < scores.length ? idx : NO_MORE_DOCS; } } @@ -71,7 +81,7 @@ TopDocsCollector tdc = TopScoreDocCollector.create(scores.length, true); Collector c = new PositiveScoresOnlyCollector(tdc); c.setScorer(s); - while (!s.next()) { + while (s.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) { c.collect(0); } TopDocs td = tdc.topDocs(); Index: src/test/org/apache/lucene/search/TestScoreCachingWrappingScorer.java =================================================================== --- src/test/org/apache/lucene/search/TestScoreCachingWrappingScorer.java (revision 775940) +++ src/test/org/apache/lucene/search/TestScoreCachingWrappingScorer.java (working copy) @@ -44,14 +44,25 @@ public int doc() { return doc; } + /** @deprecated use {@link #nextDoc()} instead. */ public boolean next() throws IOException { - return ++doc == scores.length; + return nextDoc() != NO_MORE_DOCS; } + public int nextDoc() throws IOException { + return ++doc < scores.length ? doc : NO_MORE_DOCS; + } + + /** @deprecated use {@link #advance(int)} instead. */ public boolean skipTo(int target) throws IOException { + return advance(target) != NO_MORE_DOCS; + } + + public int advance(int target) throws IOException { doc = target; - return doc >= scores.length; + return doc < scores.length ? doc : NO_MORE_DOCS; } + } private static final class ScoreCachingCollector extends Collector { @@ -98,8 +109,9 @@ scc.setScorer(s); // We need to iterate on the scorer so that its doc() advances. - while (!s.next()) { - scc.collect(s.doc()); + int doc; + while ((doc = s.nextDoc()) != DocIdSetIterator.NO_MORE_DOCS) { + scc.collect(doc); } for (int i = 0; i < scores.length; i++) { Index: src/test/org/apache/lucene/search/TestSpanQueryFilter.java =================================================================== --- src/test/org/apache/lucene/search/TestSpanQueryFilter.java (revision 775940) +++ src/test/org/apache/lucene/search/TestSpanQueryFilter.java (working copy) @@ -77,7 +77,7 @@ int getDocIdSetSize(DocIdSet docIdSet) throws Exception { int size = 0; DocIdSetIterator it = docIdSet.iterator(); - while (it.next()) { + while (it.nextDoc() != DocIdSetIterator.NO_MORE_DOCS) { size++; } return size; @@ -85,7 +85,7 @@ public void assertContainsDocId(String msg, DocIdSet docIdSet, int docId) throws Exception { DocIdSetIterator it = docIdSet.iterator(); - assertTrue(msg, it.skipTo(docId)); + assertTrue(msg, it.advance(docId) != DocIdSetIterator.NO_MORE_DOCS); assertTrue(msg, it.doc() == docId); } } Index: src/test/org/apache/lucene/search/TestTermScorer.java =================================================================== --- src/test/org/apache/lucene/search/TestTermScorer.java (revision 775940) +++ src/test/org/apache/lucene/search/TestTermScorer.java (working copy) @@ -134,11 +134,11 @@ TermScorer ts = new TermScorer(weight, indexReader.termDocs(allTerm), indexSearcher.getSimilarity(), indexReader.norms(FIELD)); - assertTrue("next did not return a doc", ts.next() == true); + assertTrue("next did not return a doc", ts.nextDoc() != DocIdSetIterator.NO_MORE_DOCS); assertTrue("score is not correct", ts.score() == 1.6931472f); - assertTrue("next did not return a doc", ts.next() == true); + assertTrue("next did not return a doc", ts.nextDoc() != DocIdSetIterator.NO_MORE_DOCS); assertTrue("score is not correct", ts.score() == 1.6931472f); - assertTrue("next returned a doc and it should not have", ts.next() == false); + assertTrue("next returned a doc and it should not have", ts.nextDoc() == DocIdSetIterator.NO_MORE_DOCS); } public void testSkipTo() throws Exception { @@ -151,7 +151,7 @@ TermScorer ts = new TermScorer(weight, indexReader.termDocs(allTerm), indexSearcher.getSimilarity(), indexReader.norms(FIELD)); - assertTrue("Didn't skip", ts.skipTo(3) == true); + assertTrue("Didn't skip", ts.advance(3) != DocIdSetIterator.NO_MORE_DOCS); //The next doc should be doc 5 assertTrue("doc should be number 5", ts.doc() == 5); } Index: src/test/org/apache/lucene/search/spans/TestNearSpansOrdered.java =================================================================== --- src/test/org/apache/lucene/search/spans/TestNearSpansOrdered.java (revision 775940) +++ src/test/org/apache/lucene/search/spans/TestNearSpansOrdered.java (working copy) @@ -165,8 +165,7 @@ SpanNearQuery q = makeQuery(); Weight w = q.createWeight(searcher); Scorer s = w.scorer(searcher.getIndexReader()); - assertEquals(true, s.skipTo(1)); - assertEquals(1, s.doc()); + assertEquals(1, s.advance(1)); } /** * not a direct test of NearSpans, but a demonstration of how/when Index: src/test/org/apache/lucene/search/spans/TestSpans.java =================================================================== --- src/test/org/apache/lucene/search/spans/TestSpans.java (revision 775940) +++ src/test/org/apache/lucene/search/spans/TestSpans.java (working copy) @@ -17,6 +17,7 @@ * limitations under the License. */ +import org.apache.lucene.search.DocIdSetIterator; import org.apache.lucene.search.IndexSearcher; import org.apache.lucene.search.Query; import org.apache.lucene.search.CheckHits; @@ -392,11 +393,11 @@ Scorer spanScorer = snq.weight(searcher).scorer(searcher.getIndexReader()); - assertTrue("first doc", spanScorer.next()); + assertTrue("first doc", spanScorer.nextDoc() != DocIdSetIterator.NO_MORE_DOCS); assertEquals("first doc number", spanScorer.doc(), 11); float score = spanScorer.score(); assertTrue("first doc score should be zero, " + score, score == 0.0f); - assertTrue("no second doc", ! spanScorer.next()); + assertTrue("no second doc", spanScorer.nextDoc() == DocIdSetIterator.NO_MORE_DOCS); } // LUCENE-1404 Index: src/test/org/apache/lucene/util/TestOpenBitSet.java =================================================================== --- src/test/org/apache/lucene/util/TestOpenBitSet.java (revision 775940) +++ src/test/org/apache/lucene/util/TestOpenBitSet.java (working copy) @@ -20,6 +20,8 @@ import java.util.Random; import java.util.BitSet; +import org.apache.lucene.search.DocIdSetIterator; + /** * @version $Id$ */ @@ -55,12 +57,8 @@ OpenBitSetIterator iterator = new OpenBitSetIterator(b); do { aa = a.nextSetBit(aa+1); - if (rand.nextBoolean()) - iterator.next(); - else - iterator.skipTo(bb+1); - bb = iterator.doc(); - assertEquals(aa,bb); + bb = rand.nextBoolean() ? iterator.nextDoc() : iterator.advance(bb + 1); + assertEquals(aa == -1 ? DocIdSetIterator.NO_MORE_DOCS : aa, bb); } while (aa>=0); } @@ -69,11 +67,8 @@ OpenBitSetIterator iterator = new OpenBitSetIterator(b); do { aa = a.nextSetBit(aa+1); - if (rand.nextBoolean()) - bb = iterator.nextDoc(); - else - bb = iterator.next(bb+1); - assertEquals(aa,bb); + bb = rand.nextBoolean() ? iterator.nextDoc() : iterator.advance(bb + 1); + assertEquals(aa == -1 ? DocIdSetIterator.NO_MORE_DOCS : aa, bb); } while (aa>=0); } Index: src/test/org/apache/lucene/util/TestSortedVIntList.java =================================================================== --- src/test/org/apache/lucene/util/TestSortedVIntList.java (revision 775940) +++ src/test/org/apache/lucene/util/TestSortedVIntList.java (working copy) @@ -42,10 +42,10 @@ } DocIdSetIterator m = vintList.iterator(); for (int i = 0; i < ints.length; i++) { - assertTrue("No end of Matcher at: " + i, m.next()); + assertTrue("No end of Matcher at: " + i, m.nextDoc() != DocIdSetIterator.NO_MORE_DOCS); assertEquals(ints[i], m.doc()); } - assertTrue("End of Matcher", (! m.next())); + assertTrue("End of Matcher", m.nextDoc() == DocIdSetIterator.NO_MORE_DOCS); } void tstVIntList( @@ -143,9 +143,6 @@ public void test02() { tstInts(new int[] {0}); } - public void test03() { - tstInts(new int[] {0,Integer.MAX_VALUE}); - } public void test04a() { tstInts(new int[] {0, VB2 - 1}); } Index: tags/lucene_2_4_back_compat_tests_20090509/src/java/org/apache/lucene/util/OpenBitSetIterator.java =================================================================== --- tags/lucene_2_4_back_compat_tests_20090509/src/java/org/apache/lucene/util/OpenBitSetIterator.java (revision 778102) +++ tags/lucene_2_4_back_compat_tests_20090509/src/java/org/apache/lucene/util/OpenBitSetIterator.java (working copy) @@ -197,7 +197,7 @@ /** Behaves like {@link #skipTo(int)} and returns the docId the iterator * skipped to; returns -1 if no valid document could be skipped to. */ - public int next(int fromIndex) { + public int advance(int fromIndex) { indexArray=0; i = fromIndex >> 6; if (i>=words) { Index: tags/lucene_2_4_back_compat_tests_20090509/src/test/org/apache/lucene/util/TestOpenBitSet.java =================================================================== --- tags/lucene_2_4_back_compat_tests_20090509/src/test/org/apache/lucene/util/TestOpenBitSet.java (revision 778102) +++ tags/lucene_2_4_back_compat_tests_20090509/src/test/org/apache/lucene/util/TestOpenBitSet.java (working copy) @@ -74,8 +74,8 @@ if (rand.nextBoolean()) bb = iterator.nextDoc(); else - bb = iterator.next(bb+1); - assertEquals(aa,bb); + bb = iterator.advance(bb + 1); + assertEquals(aa == -1 ? Integer.MAX_VALUE : aa,bb); } while (aa>=0); } Index: tags/lucene_2_4_back_compat_tests_20090509/src/test/org/apache/lucene/util/TestSortedVIntList.java =================================================================== --- tags/lucene_2_4_back_compat_tests_20090509/src/test/org/apache/lucene/util/TestSortedVIntList.java (revision 778102) +++ tags/lucene_2_4_back_compat_tests_20090509/src/test/org/apache/lucene/util/TestSortedVIntList.java (working copy) @@ -143,9 +143,6 @@ public void test02() { tstInts(new int[] {0}); } - public void test03() { - tstInts(new int[] {0,Integer.MAX_VALUE}); - } public void test04a() { tstInts(new int[] {0, VB2 - 1}); }