You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@lucene.apache.org by ho...@apache.org on 2007/10/05 03:53:30 UTC
svn commit: r582054 - in
/lucene/java/trunk/src/java/org/apache/lucene/search: BooleanQuery.java
Scorer.java
Author: hossman
Date: Thu Oct 4 18:53:29 2007
New Revision: 582054
URL: http://svn.apache.org/viewvc?rev=582054&view=rev
Log:
more explicit javadocs about Scorer contract for iterating in doc id order
Modified:
lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java
lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java
Modified: lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java
URL: http://svn.apache.org/viewvc/lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java?rev=582054&r1=582053&r2=582054&view=diff
==============================================================================
--- lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java (original)
+++ lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java Thu Oct 4 18:53:29 2007
@@ -313,15 +313,25 @@
private static boolean allowDocsOutOfOrder = false;
/**
- * Indicates whether hit docs may be collected out of docid
- * order. In other words, with this setting,
+ * Expert: Indicates whether hit docs may be collected out of docid
+ * order.
+ *
+ * <p>
+ * Background: llthough the contract of the Scorer class requires that
+ * documents be iterated in order of doc id this was not true in early
+ * versions of Lucene. Many pieces of functionality in the current
+ * Lucene code base have undefined behavior if this contract is not
+ * upheld, but in some specific simple cases may be faster. (For
+ * example: disjunction queries with less than 32 prohibited clauses;
+ * This setting has no effect for other queries.)
+ * </p>
+ *
+ * <p>
+ * Specifics: By setting this option to this true, calls to
* {@link HitCollector#collect(int,float)} might be
* invoked first for docid N and only later for docid N-1.
* Being static, this setting is system wide.
- * If collecting docs out of order is allowed, scoring might be faster
- * for certain queries, for example disjunction queries with
- * less than 32 prohibited clauses.
- * This setting has no effect for other queries.
+ * </p>
*/
public static void setAllowDocsOutOfOrder(boolean allow) {
allowDocsOutOfOrder = allow;
Modified: lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java
URL: http://svn.apache.org/viewvc/lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java?rev=582054&r1=582053&r2=582054&view=diff
==============================================================================
--- lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java (original)
+++ lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java Thu Oct 4 18:53:29 2007
@@ -19,10 +19,19 @@
import java.io.IOException;
-/** Expert: Common scoring functionality for different types of queries.
- * <br>A <code>Scorer</code> either iterates over documents matching a query,
- * or provides an explanation of the score for a query for a given document.
- * <br>Document scores are computed using a given <code>Similarity</code> implementation.
+/**
+ * Expert: Common scoring functionality for different types of queries.
+ *
+ * <p>
+ * A <code>Scorer</code> either iterates over documents matching a
+ * query in increasing order of doc Id, or provides an explanation of
+ * the score for a query for a given document.
+ * </p>
+ * <p>
+ * Document scores are computed using a given <code>Similarity</code>
+ * implementation.
+ * </p>
+ * @see BooleanQuery#setAllowDocsOutOfOrder
*/
public abstract class Scorer {
private Similarity similarity;
@@ -67,9 +76,19 @@
return true;
}
- /** Advances to the next document matching the query.
+ /**
+ * Advances to the document matching this Scorer with the lowest doc Id
+ * greater then the current value of {@link doc()} (or to the matching
+ * document with the lowest doc Id if next has never been called on
+ * this Scorer).
+ *
+ * <p>
+ * When this method is used the {@link #explain(int)} method should not
+ * be used.
+ * </p>
+ *
* @return true iff there is another document matching the query.
- * <br>When this method is used the {@link #explain(int)} method should not be used.
+ * @see BooleanQuery#setAllowDocsOutOfOrder
*/
public abstract boolean next() throws IOException;
@@ -84,12 +103,16 @@
*/
public abstract float score() throws IOException;
- /** Skips to the first match beyond the current whose document number is
+ /**
+ * Skips to the document matching this Scorer with the lowest doc Id
* greater than or equal to a given target.
- * <br>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.
- * <p>Behaves as if written: <pre>
+ *
+ * <p>
+ * The behavior of this method is undefined if the target specified is
+ * less then or equal to the current value of {@link #doc()}
+ * <p>
+ * Behaves as if written:
+ * <pre>
* boolean skipTo(int target) {
* do {
* if (!next())
@@ -97,7 +120,18 @@
* } while (target > doc());
* return true;
* }
- * </pre>Most implementations are considerably more efficient than that.
+ * </pre>
+ * Most implementations are considerably more efficient than that.
+ * </p>
+ *
+ * <p>
+ * When this method is used the {@link #explain(int)} method should not
+ * be used.
+ * </p>
+ *
+ * @param target The target document number.
+ * @return true iff there is such a match.
+ * @see BooleanQuery#setAllowDocsOutOfOrder
*/
public abstract boolean skipTo(int target) throws IOException;
Re: svn commit: r582054: typo
Posted by Paul Elschot <pa...@xs4all.nl>.
Hoss,
Thanks for that.
There is a typo, it says "llthough" in one of the javadocs.
Regards,
Paul Elschot
---------------------------------------------------------------------
To unsubscribe, e-mail: java-dev-unsubscribe@lucene.apache.org
For additional commands, e-mail: java-dev-help@lucene.apache.org