← Back to branch summary

~slub.team/goobi-indexserver/3.x

« back to all changes in this revision

Viewing changes to lucene/src/java/org/apache/lucene/search/Scorer.java

  • Committer: Sebastian Meyer
  • Date: 2012-08-03 09:12:40 UTC
  • Revision ID: sebastian.meyer@slub-dresden.de-20120803091240-x6861b0vabq1xror
https://launchpad.net/bugs/985487
Remove Lucene and Solr source code and add patches instead
Fix Bug #985487: Auto-suggestion for the search interface

Show diffs side-by-side

added added

removed removed

Lines of Context:
lucene/src/java/org/apache/lucene/search/Scorer.java
1
 
package org.apache.lucene.search;
2
 
 
3
 
/**
4
 
 * Licensed to the Apache Software Foundation (ASF) under one or more
5
 
 * contributor license agreements.  See the NOTICE file distributed with
6
 
 * this work for additional information regarding copyright ownership.
7
 
 * The ASF licenses this file to You under the Apache License, Version 2.0
8
 
 * (the "License"); you may not use this file except in compliance with
9
 
 * the License.  You may obtain a copy of the License at
10
 
 *
11
 
 *     http://www.apache.org/licenses/LICENSE-2.0
12
 
 *
13
 
 * Unless required by applicable law or agreed to in writing, software
14
 
 * distributed under the License is distributed on an "AS IS" BASIS,
15
 
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16
 
 * See the License for the specific language governing permissions and
17
 
 * limitations under the License.
18
 
 */
19
 
 
20
 
import java.io.IOException;
21
 
 
22
 
import org.apache.lucene.search.BooleanClause.Occur;
23
 
 
24
 
/**
25
 
 * Expert: Common scoring functionality for different types of queries.
26
 
 *
27
 
 * <p>
28
 
 * A <code>Scorer</code> iterates over documents matching a
29
 
 * query in increasing order of doc Id.
30
 
 * </p>
31
 
 * <p>
32
 
 * Document scores are computed using a given <code>Similarity</code>
33
 
 * implementation.
34
 
 * </p>
35
 
 *
36
 
 * <p><b>NOTE</b>: The values Float.Nan,
37
 
 * Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are
38
 
 * not valid scores.  Certain collectors (eg {@link
39
 
 * TopScoreDocCollector}) will not properly collect hits
40
 
 * with these scores.
41
 
 */
42
 
public abstract class Scorer extends DocIdSetIterator {
43
 
  private final Similarity similarity;
44
 
  protected final Weight weight;
45
 
 
46
 
  /**
47
 
   * Constructs a Scorer
48
 
   * @param weight The scorers <code>Weight</code>.
49
 
   */
50
 
  protected Scorer(Weight weight) {
51
 
    this(null, weight);
52
 
  }
53
 
  
54
 
  /** Constructs a Scorer.
55
 
   * @param similarity The <code>Similarity</code> implementation used by this scorer.
56
 
   * @deprecated Use {@link #Scorer(Weight)} instead.
57
 
   */
58
 
  @Deprecated
59
 
  protected Scorer(Similarity similarity) {
60
 
    this(similarity, null);
61
 
  }
62
 
  
63
 
  /**
64
 
   * Constructs a Scorer
65
 
   * @param similarity The <code>Similarity</code> implementation used by this scorer.
66
 
   * @param weight The scorers <code>Weight</code>
67
 
   * @deprecated Use {@link #Scorer(Weight)} instead.
68
 
   */
69
 
  @Deprecated
70
 
  protected Scorer(Similarity similarity, Weight weight) {
71
 
    this.similarity = similarity;
72
 
    this.weight = weight;
73
 
  }
74
 
 
75
 
  /** Returns the Similarity implementation used by this scorer. 
76
 
   * @deprecated Store any Similarity you might need privately in your implementation instead.
77
 
   */
78
 
  @Deprecated
79
 
  public Similarity getSimilarity() {
80
 
    return this.similarity;
81
 
  }
82
 
 
83
 
  /** Scores and collects all matching documents.
84
 
   * @param collector The collector to which all matching documents are passed.
85
 
   */
86
 
  public void score(Collector collector) throws IOException {
87
 
    collector.setScorer(this);
88
 
    int doc;
89
 
    while ((doc = nextDoc()) != NO_MORE_DOCS) {
90
 
      collector.collect(doc);
91
 
    }
92
 
  }
93
 
 
94
 
  /**
95
 
   * Expert: Collects matching documents in a range. Hook for optimization.
96
 
   * Note, <code>firstDocID</code> is added to ensure that {@link #nextDoc()}
97
 
   * was called before this method.
98
 
   *
99
 
   * <p><b>NOTE:</b> Because of backwards compatibility, this method is still
100
 
   * declared as <b>protected</b>, but it is intended to be <b>public</b>,
101
 
   * because it's called from other classes (like BooleanScorer).
102
 
   * If you subclass {@code Scorer}, you should declare the overridden method
103
 
   * as public to ease transition to Lucene 4.0, where it will be public.</p>
104
 
   * 
105
 
   * @param collector
106
 
   *          The collector to which all matching documents are passed.
107
 
   * @param max
108
 
   *          Do not score documents past this.
109
 
   * @param firstDocID
110
 
   *          The first document ID (ensures {@link #nextDoc()} is called before
111
 
   *          this method.
112
 
   * @return true if more matching documents may remain.
113
 
   */
114
 
  protected boolean score(Collector collector, int max, int firstDocID) throws IOException {
115
 
    collector.setScorer(this);
116
 
    int doc = firstDocID;
117
 
    while (doc < max) {
118
 
      collector.collect(doc);
119
 
      doc = nextDoc();
120
 
    }
121
 
    return doc != NO_MORE_DOCS;
122
 
  }
123
 
  
124
 
  /** Returns the score of the current document matching the query.
125
 
   * Initially invalid, until {@link #nextDoc()} or {@link #advance(int)}
126
 
   * is called the first time, or when called from within
127
 
   * {@link Collector#collect}.
128
 
   */
129
 
  public abstract float score() throws IOException;
130
 
 
131
 
  /** Returns number of matches for the current document.
132
 
   *  This returns a float (not int) because
133
 
   *  SloppyPhraseScorer discounts its freq according to how
134
 
   *  "sloppy" the match was.
135
 
   *
136
 
   * @lucene.experimental */
137
 
  public float freq() throws IOException {
138
 
    throw new UnsupportedOperationException(this + " does not implement freq()");
139
 
  }
140
 
 
141
 
  /**
142
 
   * A callback to gather information from a scorer and its sub-scorers. Each
143
 
   * the top-level scorer as well as each of its sub-scorers are passed to
144
 
   * either one of the visit methods depending on their boolean relationship in
145
 
   * the query.
146
 
   * @lucene.experimental
147
 
   */
148
 
  public static abstract class ScorerVisitor<P extends Query, C extends Query, S extends Scorer> {
149
 
    /**
150
 
     * Invoked for all optional scorer 
151
 
     * 
152
 
     * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
153
 
     * @param child the query of the currently visited scorer
154
 
     * @param scorer the current scorer
155
 
     */
156
 
    public void visitOptional(P parent, C child, S scorer) {}
157
 
    
158
 
    /**
159
 
     * Invoked for all required scorer 
160
 
     * 
161
 
     * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
162
 
     * @param child the query of the currently visited scorer
163
 
     * @param scorer the current scorer
164
 
     */
165
 
    public void visitRequired(P parent, C child, S scorer) {}
166
 
    
167
 
    /**
168
 
     * Invoked for all prohibited scorer 
169
 
     * 
170
 
     * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
171
 
     * @param child the query of the currently visited scorer
172
 
     * @param scorer the current scorer
173
 
     */
174
 
    public void visitProhibited(P parent, C child, S scorer) {}
175
 
  } 
176
 
 
177
 
  /**
178
 
   * Expert: call this to gather details for all sub-scorers for this query.
179
 
   * This can be used, in conjunction with a custom {@link Collector} to gather
180
 
   * details about how each sub-query matched the current hit.
181
 
   * 
182
 
   * @param visitor a callback executed for each sub-scorer
183
 
   * @lucene.experimental
184
 
   */
185
 
  public void visitScorers(ScorerVisitor<Query, Query, Scorer> visitor) {
186
 
    visitSubScorers(null, Occur.MUST/*must id default*/, visitor);
187
 
  }
188
 
 
189
 
  /**
190
 
   * {@link Scorer} subclasses should implement this method if the subclass
191
 
   * itself contains multiple scorers to support gathering details for
192
 
   * sub-scorers via {@link ScorerVisitor}
193
 
   * <p>
194
 
   * Note: this method will throw {@link UnsupportedOperationException} if no
195
 
   * associated {@link Weight} instance is provided to
196
 
   * {@link #Scorer(Weight)}
197
 
   * </p>
198
 
   * 
199
 
   * @lucene.experimental
200
 
   */
201
 
  protected void visitSubScorers(Query parent, Occur relationship,
202
 
      ScorerVisitor<Query, Query, Scorer> visitor) {
203
 
    if (weight == null)
204
 
      throw new UnsupportedOperationException();
205
 
 
206
 
    final Query q = weight.getQuery();
207
 
    switch (relationship) {
208
 
    case MUST:
209
 
      visitor.visitRequired(parent, q, this);
210
 
      break;
211
 
    case MUST_NOT:
212
 
      visitor.visitProhibited(parent, q, this);
213
 
      break;
214
 
    case SHOULD:
215
 
      visitor.visitOptional(parent, q, this);
216
 
      break;
217
 
    }
218
 
  }
219
 
}