Matcher either iterates over documents matching a query
+ * or a filter, or provides an explanation of the reason why a single document
+ * matches a query or a filter.
+ */
+public abstract class Matcher {
+ /** Collects all matching documents.
+ * @param mc The MatchCollector to which all matching documents are passed
+ * through {@link MatchCollector#collect(int)}.
+ * + * When this method is used the {@link #explain(int)} + * and {@link #match(MatchCollector)} methods should not be used. + *
+ * + * @return true iff there is another matching document. + */ + public abstract boolean next() throws IOException; + + /** Returns the current matching document number. + * Initially invalid, until {@link #next()} or {@link #skipTo(int)} + * is called the first time. + */ + public abstract int doc(); + + /** + * Skips to the document matching this Matcher with the lowest doc Id + * greater than or equal to a given target. + * + *+ * The behavior of this method is undefined if the target specified is + * less than or equal to the current value of {@link #doc()}. + *
+ * Behaves as if written: + *
+ * boolean skipTo(int target) {
+ * do {
+ * if (!next())
+ * return false;
+ * } while (target > doc());
+ * return true;
+ * }
+ *
+ * Most implementations are considerably more efficient than that.
+ *
+ *
+ * + * When this method is used the {@link #explain(int)} + * and {@link #match(MatchCollector)} methods should not be used. + *
+ * + * @param target The target document number. + * @return true iff there is such a match. + */ + public abstract boolean skipTo(int target) throws IOException; + + /** Returns an explanation of the matching of a single document. + *Applications usually need only call the inherited {@link #search(Query)} - * or {@link #search(Query,Filter)} methods. For performance reasons it is + * or {@link #search(Query,MatchFilter)} methods. For performance reasons it is * recommended to open only one IndexSearcher and use it for all of your searches. - * + * *
Note that you can only access Hits from an IndexSearcher as long as it is - * not yet closed, otherwise an IOException will be thrown. + * not yet closed, otherwise an IOException will be thrown. */ public class IndexSearcher extends Searcher { IndexReader reader; @@ -103,7 +102,7 @@ } // inherit javadoc - public TopDocs search(Weight weight, Filter filter, final int nDocs) + public TopDocs search(Weight weight, MatchFilter filter, final int nDocs) throws IOException { if (nDocs <= 0) // null might be returned from hq.top() below. @@ -115,7 +114,7 @@ } // inherit javadoc - public TopFieldDocs search(Weight weight, Filter filter, final int nDocs, + public TopFieldDocs search(Weight weight, MatchFilter filter, final int nDocs, Sort sort) throws IOException { @@ -126,26 +125,56 @@ } // inherit javadoc - public void search(Weight weight, Filter filter, + public void search(Weight weight, MatchFilter filter, final HitCollector results) throws IOException { - HitCollector collector = results; - if (filter != null) { - final BitSet bits = filter.bits(reader); - collector = new HitCollector() { - public final void collect(int doc, float score) { - if (bits.get(doc)) { // skip docs not in bits - results.collect(doc, score); - } - } - }; - } - Scorer scorer = weight.scorer(reader); if (scorer == null) return; - scorer.score(collector); + + if (filter == null) { + scorer.score(results); + return; + } + + Matcher filterMatcher = filter.getMatcher(reader); // CHECKME: use ConjunctionScorer here? + boolean more = filterMatcher.next(); + while (more) { + int filterDocNr = filterMatcher.doc(); + if (! scorer.skipTo(filterDocNr)) { + more = false; + } else { + int scorerDocNr = scorer.doc(); + if (scorerDocNr == filterDocNr) { // permitted by filter + results.collect(scorerDocNr, scorer.score()); + more = filterMatcher.skipTo(scorerDocNr + 1); + } else { + more = filterMatcher.skipTo(scorerDocNr); + } + } + } } + /** Lower-level search API. + * + *
{@link MatchCollector#collect(int)} is called for every matching
+ * document.
+ *
When filtering of the results is needed use a {@link FilteredQuery}
+ * for the query argument.
+ *
MatchCollector-based access to remote indexes is discouraged.
+ *
+ *
Applications should only use this if they need all of the
+ * matching documents.
+ * @throws BooleanQuery.TooManyClauses
+ * @todo Check whether a match method is needed in
+ * {@link Searcher}.
+ */
+ public void match(Query query,
+ final MatchCollector results) throws IOException {
+ Weight w = createWeight(query);
+ Matcher m = w.scorer(reader);
+ m.match(results);
+ }
+
public Query rewrite(Query original) throws IOException {
Query query = original;
for (Query rewrittenQuery = query.rewrite(reader); rewrittenQuery != query;
Index: src/java/org/apache/lucene/search/Searcher.java
===================================================================
--- src/java/org/apache/lucene/search/Searcher.java (revision 597476)
+++ src/java/org/apache/lucene/search/Searcher.java (working copy)
@@ -35,14 +35,14 @@
* @throws BooleanQuery.TooManyClauses
*/
public final Hits search(Query query) throws IOException {
- return search(query, (Filter)null);
+ return search(query, (MatchFilter)null);
}
/** Returns the documents matching query and
* filter.
* @throws BooleanQuery.TooManyClauses
*/
- public Hits search(Query query, Filter filter) throws IOException {
+ public Hits search(Query query, MatchFilter filter) throws IOException {
return new Hits(this, query, filter);
}
@@ -59,7 +59,7 @@
* sorted by sort.
* @throws BooleanQuery.TooManyClauses
*/
- public Hits search(Query query, Filter filter, Sort sort)
+ public Hits search(Query query, MatchFilter filter, Sort sort)
throws IOException {
return new Hits(this, query, filter, sort);
}
@@ -70,18 +70,18 @@
* sort.
*
*
Applications should usually call {@link - * Searcher#search(Query,Filter,Sort)} instead. + * Searcher#search(Query,MatchFilter,Sort)} instead. * @throws BooleanQuery.TooManyClauses */ - public TopFieldDocs search(Query query, Filter filter, int n, + public TopFieldDocs search(Query query, MatchFilter filter, int n, Sort sort) throws IOException { return search(createWeight(query), filter, n, sort); } /** Lower-level search API. * - *
{@link HitCollector#collect(int,float)} is called for every non-zero - * scoring document. + *
{@link HitCollector#collect(int,float)} is called for every matching + * document. * *
Applications should only use this if they need all of the * matching documents. The high-level search API ({@link @@ -94,13 +94,13 @@ */ public void search(Query query, HitCollector results) throws IOException { - search(query, (Filter)null, results); + search(query, (MatchFilter)null, results); } /** Lower-level search API. * - *
{@link HitCollector#collect(int,float)} is called for every non-zero - * scoring document. + *
{@link HitCollector#collect(int,float)} is called for every matching
+ * document.
*
HitCollector-based access to remote indexes is discouraged.
*
*
Applications should only use this if they need all of the
@@ -109,25 +109,26 @@
* non-high-scoring hits.
*
* @param query to match documents
- * @param filter if non-null, a bitset used to eliminate some documents
+ * @param filter if non-null, used to permit documents to be collected.
* @param results to receive hits
* @throws BooleanQuery.TooManyClauses
*/
- public void search(Query query, Filter filter, HitCollector results)
+ public void search(Query query, MatchFilter filter, HitCollector results)
throws IOException {
search(createWeight(query), filter, results);
}
/** Expert: Low-level search implementation. Finds the top n
- * hits for query, applying filter if non-null.
+ * hits for query, applying filter if non-null
+ * for documents to be permitted in the top n hits.
*
*
Called by {@link Hits}. * *
Applications should usually call {@link Searcher#search(Query)} or - * {@link Searcher#search(Query,Filter)} instead. + * {@link Searcher#search(Query,MatchFilter)} instead. * @throws BooleanQuery.TooManyClauses */ - public TopDocs search(Query query, Filter filter, int n) + public TopDocs search(Query query, MatchFilter filter, int n) throws IOException { return search(createWeight(query), filter, n); } @@ -183,14 +184,14 @@ /* The following abstract methods were added as a workaround for GCJ bug #15411. * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=15411 */ - abstract public void search(Weight weight, Filter filter, HitCollector results) throws IOException; + abstract public void search(Weight weight, MatchFilter filter, HitCollector results) throws IOException; abstract public void close() throws IOException; abstract public int docFreq(Term term) throws IOException; abstract public int maxDoc() throws IOException; - abstract public TopDocs search(Weight weight, Filter filter, int n) throws IOException; + abstract public TopDocs search(Weight weight, MatchFilter filter, int n) throws IOException; abstract public Document doc(int i) throws CorruptIndexException, IOException; abstract public Query rewrite(Query query) throws IOException; abstract public Explanation explain(Weight weight, int doc) throws IOException; - abstract public TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort) throws IOException; + abstract public TopFieldDocs search(Weight weight, MatchFilter filter, int n, Sort sort) throws IOException; /* End patch for GCJ bug #15411. */ } Index: src/java/org/apache/lucene/search/Searchable.java =================================================================== --- src/java/org/apache/lucene/search/Searchable.java (revision 597476) +++ src/java/org/apache/lucene/search/Searchable.java (working copy) @@ -33,26 +33,26 @@ * *
Queries, filters and sort criteria are designed to be compact so that * they may be efficiently passed to a remote index, with only the top-scoring - * hits being returned, rather than every non-zero scoring hit. + * hits being returned, rather than every matching hit. */ public interface Searchable extends java.rmi.Remote { /** Lower-level search API. * - *
{@link HitCollector#collect(int,float)} is called for every non-zero - * scoring document. + *
{@link HitCollector#collect(int,float)} is called for every
+ * matching document.
*
HitCollector-based access to remote indexes is discouraged.
*
*
Applications should only use this if they need all of the - * matching documents. The high-level search API ({@link - * Searcher#search(Query)}) is usually more efficient, as it skips - * non-high-scoring hits. + * matching documents and their score values. + * The high-level search API ({@link Searcher#search(Query)}) is usually more + * efficient, as it skips non-high-scoring hits. * * @param weight to match documents * @param filter if non-null, a bitset used to eliminate some documents * @param results to receive hits * @throws BooleanQuery.TooManyClauses */ - void search(Weight weight, Filter filter, HitCollector results) + void search(Weight weight, MatchFilter filter, HitCollector results) throws IOException; @@ -86,13 +86,14 @@ *
Called by {@link Hits}. * *
Applications should usually call {@link Searcher#search(Query)} or
- * {@link Searcher#search(Query,Filter)} instead.
+ * {@link Searcher#search(Query,MatchFilter)} instead.
* @throws BooleanQuery.TooManyClauses
*/
- TopDocs search(Weight weight, Filter filter, int n) throws IOException;
+ TopDocs search(Weight weight, MatchFilter filter, int n) throws IOException;
/** Expert: Returns the stored fields of document i.
- * Called by {@link HitCollector} implementations.
+ * Called by {@link HitCollector} and {@link MatchCollector} implementations,
+ * normally after the inner search loop.
* @see IndexReader#document(int)
* @throws CorruptIndexException if the index is corrupt
* @throws IOException if there is a low-level IO error
@@ -146,10 +147,10 @@
* sort.
*
*
Applications should usually call {@link - * Searcher#search(Query,Filter,Sort)} instead. + * Searcher#search(Query,MatchFilter,Sort)} instead. * @throws BooleanQuery.TooManyClauses */ - TopFieldDocs search(Weight weight, Filter filter, int n, Sort sort) + TopFieldDocs search(Weight weight, MatchFilter filter, int n, Sort sort) throws IOException; } Index: src/java/org/apache/lucene/search/TopDocs.java =================================================================== --- src/java/org/apache/lucene/search/TopDocs.java (revision 597476) +++ src/java/org/apache/lucene/search/TopDocs.java (working copy) @@ -18,7 +18,7 @@ */ /** Expert: Returned by low-level search implementations. - * @see Searcher#search(Query,Filter,int) */ + * @see Searcher#search(Query,MatchFilter,int) */ public class TopDocs implements java.io.Serializable { /** Expert: The total number of hits for the query. * @see Hits#length() Index: src/java/org/apache/lucene/search/TopFieldDocs.java =================================================================== --- src/java/org/apache/lucene/search/TopFieldDocs.java (revision 597476) +++ src/java/org/apache/lucene/search/TopFieldDocs.java (working copy) @@ -26,7 +26,7 @@ * @author Tim Jones (Nacimiento Software) * @since lucene 1.4 * @version $Id$ - * @see Searcher#search(Query,Filter,int,Sort) + * @see Searcher#search(Query,MatchFilter,int,Sort) */ public class TopFieldDocs extends TopDocs { Index: src/java/org/apache/lucene/search/HitCollector.java =================================================================== --- src/java/org/apache/lucene/search/HitCollector.java (revision 597476) +++ src/java/org/apache/lucene/search/HitCollector.java (working copy) @@ -27,26 +27,13 @@ /** Called once for every document matching a query, with the document * number and its raw score. * - *
If, for example, an application wished to collect all of the hits for a - * query in a BitSet, then it might:
- * Searcher searcher = new IndexSearcher(indexReader);
- * final BitSet bits = new BitSet(indexReader.maxDoc());
- * searcher.search(query, new HitCollector() {
- * public void collect(int doc, float score) {
- * bits.set(doc);
- * }
- * });
- *
- *
- * Note: This is called in an inner search loop. For good search - * performance, implementations of this method should not call - * {@link Searcher#doc(int)} or - * {@link org.apache.lucene.index.IndexReader#document(int)} on every - * document number encountered. Doing so can slow searches by an order - * of magnitude or more. *
Note: The score passed to this method is a raw score.
* In other words, the score will not necessarily be a float whose value is
* between 0 and 1.
+ *
+ *
For good performance of inner search loops involving a
+ * HitCollector see the advice given at
+ * {@link MatchCollector#collect(int)}.
*/
public abstract void collect(int doc, float score);
}
Index: src/java/org/apache/lucene/search/MatchCollector.java
===================================================================
--- src/java/org/apache/lucene/search/MatchCollector.java (revision 0)
+++ src/java/org/apache/lucene/search/MatchCollector.java (revision 0)
@@ -0,0 +1,45 @@
+package org.apache.lucene.search;
+
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Lower-level search API.
+ * @see Matcher#match(MatchCollector)
+ */
+public abstract class MatchCollector {
+ /** Called once for every matching document, with the document number.
+ *
+ *
If, for example, an application wished to collect all of the hits for a + * query in a BitSet, then it might:
+ * IndexSearcher searcher = new IndexSearcher(indexReader);
+ * final BitSet bits = new BitSet(indexReader.maxDoc());
+ * searcher.match(query, new MatchCollector() {
+ * public void collect(int doc) {
+ * bits.set(doc);
+ * }
+ * });
+ *
+ *
+ * Note: This is called in an inner search loop. For good search
+ * performance, implementations of this method should not call
+ * {@link Searcher#doc(int)} or
+ * {@link org.apache.lucene.index.IndexReader#document(int)} on every
+ * document number encountered. Doing so can slow searches by an order
+ * of magnitude or more.
+ */
+ public abstract void collect(int doc);
+}
Property changes on: src/java/org/apache/lucene/search/MatchCollector.java
___________________________________________________________________
Name: svn:eol-style
+ native
Index: src/java/org/apache/lucene/search/MultiSearcher.java
===================================================================
--- src/java/org/apache/lucene/search/MultiSearcher.java (revision 597476)
+++ src/java/org/apache/lucene/search/MultiSearcher.java (working copy)
@@ -31,7 +31,7 @@
/** Implements search over a set of Searchables.
*
*
Applications usually need only call the inherited {@link #search(Query)}
- * or {@link #search(Query,Filter)} methods.
+ * or {@link #search(Query,MatchFilter)} methods.
*/
public class MultiSearcher extends Searcher {
/**
@@ -96,15 +96,15 @@
throw new UnsupportedOperationException();
}
- public void search(Weight weight, Filter filter, HitCollector results) {
+ public void search(Weight weight, MatchFilter filter, HitCollector results) {
throw new UnsupportedOperationException();
}
- public TopDocs search(Weight weight,Filter filter,int n) {
+ public TopDocs search(Weight weight,MatchFilter filter,int n) {
throw new UnsupportedOperationException();
}
- public TopFieldDocs search(Weight weight,Filter filter,int n,Sort sort) {
+ public TopFieldDocs search(Weight weight,MatchFilter filter,int n,Sort sort) {
throw new UnsupportedOperationException();
}
}
@@ -194,7 +194,7 @@
return maxDoc;
}
- public TopDocs search(Weight weight, Filter filter, int nDocs)
+ public TopDocs search(Weight weight, MatchFilter filter, int nDocs)
throws IOException {
HitQueue hq = new HitQueue(nDocs);
@@ -221,7 +221,7 @@
return new TopDocs(totalHits, scoreDocs, maxScore);
}
- public TopFieldDocs search (Weight weight, Filter filter, int n, Sort sort)
+ public TopFieldDocs search (Weight weight, MatchFilter filter, int n, Sort sort)
throws IOException {
FieldDocSortedHitQueue hq = null;
int totalHits = 0;
@@ -252,7 +252,7 @@
// inherit javadoc
- public void search(Weight weight, Filter filter, final HitCollector results)
+ public void search(Weight weight, MatchFilter filter, final HitCollector results)
throws IOException {
for (int i = 0; i < searchables.length; i++) {
Index: src/java/org/apache/lucene/search/ParallelMultiSearcher.java
===================================================================
--- src/java/org/apache/lucene/search/ParallelMultiSearcher.java (revision 597476)
+++ src/java/org/apache/lucene/search/ParallelMultiSearcher.java (working copy)
@@ -25,7 +25,7 @@
/** Implements parallel search over a set of Searchables.
*
*
Applications usually need only call the inherited {@link #search(Query)} - * or {@link #search(Query,Filter)} methods. + * or {@link #search(Query,MatchFilter)} methods. */ public class ParallelMultiSearcher extends MultiSearcher { @@ -51,7 +51,7 @@ * Searchable, waits for each search to complete and merge * the results back together. */ - public TopDocs search(Weight weight, Filter filter, int nDocs) + public TopDocs search(Weight weight, MatchFilter filter, int nDocs) throws IOException { HitQueue hq = new HitQueue(nDocs); int totalHits = 0; @@ -101,7 +101,7 @@ * Searchable, waits for each search to complete and merges * the results back together. */ - public TopFieldDocs search(Weight weight, Filter filter, int nDocs, Sort sort) + public TopFieldDocs search(Weight weight, MatchFilter filter, int nDocs, Sort sort) throws IOException { // don't specify the fields - we'll wait to do this until we get results FieldDocSortedHitQueue hq = new FieldDocSortedHitQueue (null, nDocs); @@ -164,7 +164,7 @@ * * @todo parallelize this one too */ - public void search(Weight weight, Filter filter, final HitCollector results) + public void search(Weight weight, MatchFilter filter, final HitCollector results) throws IOException { for (int i = 0; i < searchables.length; i++) { @@ -196,7 +196,7 @@ private Searchable searchable; private Weight weight; - private Filter filter; + private MatchFilter filter; private int nDocs; private TopDocs docs; private int i; @@ -208,7 +208,7 @@ public MultiSearcherThread( Searchable searchable, Weight weight, - Filter filter, + MatchFilter filter, int nDocs, HitQueue hq, int i, @@ -227,7 +227,7 @@ public MultiSearcherThread( Searchable searchable, Weight weight, - Filter filter, + MatchFilter filter, int nDocs, FieldDocSortedHitQueue hq, Sort sort, Index: src/java/org/apache/lucene/search/RemoteSearchable.java =================================================================== --- src/java/org/apache/lucene/search/RemoteSearchable.java (revision 597476) +++ src/java/org/apache/lucene/search/RemoteSearchable.java (working copy) @@ -46,7 +46,7 @@ } - public void search(Weight weight, Filter filter, HitCollector results) + public void search(Weight weight, MatchFilter filter, HitCollector results) throws IOException { local.search(weight, filter, results); } @@ -68,12 +68,12 @@ return local.maxDoc(); } - public TopDocs search(Weight weight, Filter filter, int n) throws IOException { + public TopDocs search(Weight weight, MatchFilter filter, int n) throws IOException { return local.search(weight, filter, n); } - public TopFieldDocs search (Weight weight, Filter filter, int n, Sort sort) + public TopFieldDocs search (Weight weight, MatchFilter filter, int n, Sort sort) throws IOException { return local.search (weight, filter, n, sort); } Index: src/java/org/apache/lucene/search/package.html =================================================================== --- src/java/org/apache/lucene/search/package.html (revision 597476) +++ src/java/org/apache/lucene/search/package.html (working copy) @@ -23,7 +23,7 @@ Applications usually call {@link org.apache.lucene.search.Searcher#search(Query)} or {@link -org.apache.lucene.search.Searcher#search(Query,Filter)}. +org.apache.lucene.search.Searcher#search(Query,MatchFilter)}.