+ * 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
+ * Note: this method will throw {@link UnsupportedOperationException} if no
+ * associated {@link Weight} instance is provided to
+ * {@link #Scorer(Weight)}
+ * 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