/*
* 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.
*/
package org.apache.lucene.search;
import java.io.IOException;
import org.apache.lucene.util.Bits;
/** This class is used to score a range of documents at
* once, and is returned by {@link Weight#bulkScorer}. Only
* queries that have a more optimized means of scoring
* across a range of documents need to override this.
* Otherwise, a default implementation is wrapped around
* the {@link Scorer} returned by {@link Weight#scorer}. */
public abstract class BulkScorer {
/** Scores and collects all matching documents.
* @param collector The collector to which all matching documents are passed.
* @param acceptDocs {@link Bits} that represents the allowed documents to match, or
* {@code null} if they are all allowed to match.
*/
public void score(LeafCollector collector, Bits acceptDocs) throws IOException {
final int next = score(collector, acceptDocs, 0, DocIdSetIterator.NO_MORE_DOCS);
assert next == DocIdSetIterator.NO_MORE_DOCS;
}
/**
* Collects matching documents in a range and return an estimation of the
* next matching document which is on or after {@code max}.
* <p>The return value must be:</p><ul>
* <li>>= {@code max},</li>
* <li>{@link DocIdSetIterator#NO_MORE_DOCS} if there are no more matches,</li>
* <li><= the first matching document that is >= {@code max} otherwise.</li>
* </ul>
* <p>{@code min} is the minimum document to be considered for matching. All
* documents strictly before this value must be ignored.</p>
* <p>Although {@code max} would be a legal return value for this method, higher
* values might help callers skip more efficiently over non-matching portions
* of the docID space.</p>
* <p>For instance, a {@link Scorer}-based implementation could look like
* below:</p>
* <pre class="prettyprint">
* private final Scorer scorer; // set via constructor
*
* public int score(LeafCollector collector, Bits acceptDocs, int min, int max) throws IOException {
* collector.setScorer(scorer);
* int doc = scorer.docID();
* if (doc < min) {
* doc = scorer.advance(min);
* }
* while (doc < max) {
* if (acceptDocs == null || acceptDocs.get(doc)) {
* collector.collect(doc);
* }
* doc = scorer.nextDoc();
* }
* return doc;
* }
* </pre>
*
* @param collector The collector to which all matching documents are passed.
* @param acceptDocs {@link Bits} that represents the allowed documents to match, or
* {@code null} if they are all allowed to match.
* @param min Score starting at, including, this document
* @param max Score up to, but not including, this doc
* @return an under-estimation of the next matching doc after max
*/
public abstract int score(LeafCollector collector, Bits acceptDocs, int min, int max) throws IOException;
/**
* Same as {@link DocIdSetIterator#cost()} for bulk scorers.
*/
public abstract long cost();
}