| /* |
| * 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: |
| * |
| * <ul> |
| * <li>>= {@code max}, |
| * <li>{@link DocIdSetIterator#NO_MORE_DOCS} if there are no more matches, |
| * <li><= the first matching document that is >= {@code max} otherwise. |
| * </ul> |
| * |
| * <p>{@code min} is the minimum document to be considered for matching. All documents strictly |
| * before this value must be ignored. |
| * |
| * <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>For instance, a {@link Scorer}-based implementation could look like below: |
| * |
| * <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(); |
| } |