--- /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