+++ /dev/null
-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.
- */
-
-import java.io.IOException;
-
-import org.apache.lucene.search.BooleanClause.Occur;
-
-/**
- * Expert: Common scoring functionality for different types of queries.
- *
- * <p>
- * A <code>Scorer</code> iterates over documents matching a
- * query in increasing order of doc Id.
- * </p>
- * <p>
- * Document scores are computed using a given <code>Similarity</code>
- * implementation.
- * </p>
- *
- * <p><b>NOTE</b>: The values Float.Nan,
- * Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are
- * not valid scores. Certain collectors (eg {@link
- * TopScoreDocCollector}) will not properly collect hits
- * with these scores.
- */
-public abstract class Scorer extends DocIdSetIterator {
- private final Similarity similarity;
- protected final Weight weight;
-
- /**
- * Constructs a Scorer
- * @param weight The scorers <code>Weight</code>.
- */
- protected Scorer(Weight weight) {
- this(null, weight);
- }
-
- /** Constructs a Scorer.
- * @param similarity The <code>Similarity</code> implementation used by this scorer.
- * @deprecated Use {@link #Scorer(Weight)} instead.
- */
- @Deprecated
- protected Scorer(Similarity similarity) {
- this(similarity, null);
- }
-
- /**
- * Constructs a Scorer
- * @param similarity The <code>Similarity</code> implementation used by this scorer.
- * @param weight The scorers <code>Weight</code>
- * @deprecated Use {@link #Scorer(Weight)} instead.
- */
- @Deprecated
- protected Scorer(Similarity similarity, Weight weight) {
- this.similarity = similarity;
- this.weight = weight;
- }
-
- /** Returns the Similarity implementation used by this scorer.
- * @deprecated Store any Similarity you might need privately in your implementation instead.
- */
- @Deprecated
- public Similarity getSimilarity() {
- return this.similarity;
- }
-
- /** Scores and collects all matching documents.
- * @param collector The collector to which all matching documents are passed.
- */
- public void score(Collector collector) throws IOException {
- collector.setScorer(this);
- int doc;
- while ((doc = nextDoc()) != NO_MORE_DOCS) {
- collector.collect(doc);
- }
- }
-
- /**
- * Expert: Collects matching documents in a range. Hook for optimization.
- * Note, <code>firstDocID</code> is added to ensure that {@link #nextDoc()}
- * was called before this method.
- *
- * <p><b>NOTE:</b> Because of backwards compatibility, this method is still
- * declared as <b>protected</b>, but it is intended to be <b>public</b>,
- * because it's called from other classes (like BooleanScorer).
- * If you subclass {@code Scorer}, you should declare the overridden method
- * as public to ease transition to Lucene 4.0, where it will be public.</p>
- *
- * @param collector
- * The collector to which all matching documents are passed.
- * @param max
- * Do not score documents past this.
- * @param firstDocID
- * The first document ID (ensures {@link #nextDoc()} is called before
- * this method.
- * @return true if more matching documents may remain.
- */
- protected boolean score(Collector collector, int max, int firstDocID) throws IOException {
- collector.setScorer(this);
- int doc = firstDocID;
- while (doc < max) {
- collector.collect(doc);
- doc = nextDoc();
- }
- return doc != NO_MORE_DOCS;
- }
-
- /** Returns the score of the current document matching the query.
- * Initially invalid, until {@link #nextDoc()} or {@link #advance(int)}
- * is called the first time, or when called from within
- * {@link Collector#collect}.
- */
- public abstract float score() throws IOException;
-
- /** Returns number of matches for the current document.
- * This returns a float (not int) because
- * SloppyPhraseScorer discounts its freq according to how
- * "sloppy" the match was.
- *
- * @lucene.experimental */
- public float freq() throws IOException {
- throw new UnsupportedOperationException(this + " does not implement freq()");
- }
-
- /**
- * A callback to gather information from a scorer and its sub-scorers. Each
- * the top-level scorer as well as each of its sub-scorers are passed to
- * either one of the visit methods depending on their boolean relationship in
- * the query.
- * @lucene.experimental
- */
- public static abstract class ScorerVisitor<P extends Query, C extends Query, S extends Scorer> {
- /**
- * Invoked for all optional scorer
- *
- * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
- * @param child the query of the currently visited scorer
- * @param scorer the current scorer
- */
- public void visitOptional(P parent, C child, S scorer) {}
-
- /**
- * Invoked for all required scorer
- *
- * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
- * @param child the query of the currently visited scorer
- * @param scorer the current scorer
- */
- public void visitRequired(P parent, C child, S scorer) {}
-
- /**
- * Invoked for all prohibited scorer
- *
- * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
- * @param child the query of the currently visited scorer
- * @param scorer the current scorer
- */
- public void visitProhibited(P parent, C child, S scorer) {}
- }
-
- /**
- * Expert: call this to gather details for all sub-scorers for this query.
- * This can be used, in conjunction with a custom {@link Collector} to gather
- * details about how each sub-query matched the current hit.
- *
- * @param visitor a callback executed for each sub-scorer
- * @lucene.experimental
- */
- public void visitScorers(ScorerVisitor<Query, Query, Scorer> visitor) {
- visitSubScorers(null, Occur.MUST/*must id default*/, visitor);
- }
-
- /**
- * {@link Scorer} subclasses should implement this method if the subclass
- * itself contains multiple scorers to support gathering details for
- * sub-scorers via {@link ScorerVisitor}
- * <p>
- * Note: this method will throw {@link UnsupportedOperationException} if no
- * associated {@link Weight} instance is provided to
- * {@link #Scorer(Weight)}
- * </p>
- *
- * @lucene.experimental
- */
- protected void visitSubScorers(Query parent, Occur relationship,
- ScorerVisitor<Query, Query, Scorer> visitor) {
- if (weight == null)
- throw new UnsupportedOperationException();
-
- final Query q = weight.getQuery();
- switch (relationship) {
- case MUST:
- visitor.visitRequired(parent, q, this);
- break;
- case MUST_NOT:
- visitor.visitProhibited(parent, q, this);
- break;
- case SHOULD:
- visitor.visitOptional(parent, q, this);
- break;
- }
- }
-}
fnp / pylucene.git / blobdiff