org.trypticon.luceneupgrader.lucene3.internal.lucene.search.Scorer Maven / Gradle / Ivy
package org.trypticon.luceneupgrader.lucene3.internal.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.trypticon.luceneupgrader.lucene3.internal.lucene.search.BooleanClause.Occur;
/**
* Expert: Common scoring functionality for different types of queries.
*
*
* A Scorer iterates over documents matching a
* query in increasing order of doc Id.
*
*
* Document scores are computed using a given Similarity
* implementation.
*
*
* NOTE: 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 Weight.
*/
protected Scorer(Weight weight) {
this(null, weight);
}
/** Constructs a Scorer.
* @param similarity The Similarity 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 Similarity implementation used by this scorer.
* @param weight The scorers Weight
* @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, firstDocID is added to ensure that {@link #nextDoc()}
* was called before this method.
*
*
NOTE: Because of backwards compatibility, this method is still
* declared as protected, but it is intended to be public,
* 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.
*
* @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 {
/**
* Invoked for all optional scorer
*
* @param parent the parent query of the child query or null 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 null 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 null 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 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}
*
* Note: this method will throw {@link UnsupportedOperationException} if no
* associated {@link Weight} instance is provided to
* {@link #Scorer(Weight)}
*
*
* @lucene.experimental
*/
public void visitSubScorers(Query parent, Occur relationship,
ScorerVisitor 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;
}
}
}