beagled/Lucene.Net/Search/Searcher.cs

   1 /*
   2  * Copyright 2004 The Apache Software Foundation
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 using System;
  18 using Document = Lucene.Net.Documents.Document;
  19 using Term = Lucene.Net.Index.Term;
  20
  21 namespace Lucene.Net.Search
  22 {
  23
  24         /// <summary>An abstract base class for search implementations.
  25         /// Implements the main search methods.
  26         ///
  27         /// <p>Note that you can only access Hits from a Searcher as long as it is
  28         /// not yet closed, otherwise an IOException will be thrown.
  29         /// </summary>
  30         public abstract class Searcher : Lucene.Net.Search.Searchable
  31         {
  32                 public Searcher()
  33                 {
  34                         InitBlock();
  35                 }
  36                 private void  InitBlock()
  37                 {
  38                         similarity = Similarity.GetDefault();
  39                 }
  40
  41                 /// <summary>Returns the documents matching <code>query</code>. </summary>
  42                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  43                 public Hits Search(Query query)
  44                 {
  45                         return Search(query, (Filter) null);
  46                 }
  47
  48                 /// <summary>Returns the documents matching <code>query</code> and
  49                 /// <code>filter</code>.
  50                 /// </summary>
  51                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  52                 public virtual Hits Search(Query query, Filter filter)
  53                 {
  54                         return new Hits(this, query, filter);
  55                 }
  56
  57                 /// <summary>Returns documents matching <code>query</code> sorted by
  58                 /// <code>sort</code>.
  59                 /// </summary>
  60                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  61                 public virtual Hits Search(Query query, Sort sort)
  62                 {
  63                         return new Hits(this, query, null, sort);
  64                 }
  65
  66                 /// <summary>Returns documents matching <code>query</code> and <code>filter</code>,
  67                 /// sorted by <code>sort</code>.
  68                 /// </summary>
  69                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  70                 public virtual Hits Search(Query query, Filter filter, Sort sort)
  71                 {
  72                         return new Hits(this, query, filter, sort);
  73                 }
  74
  75                 /// <summary>Expert: Low-level search implementation with arbitrary sorting.  Finds
  76                 /// the top <code>n</code> hits for <code>query</code>, applying
  77                 /// <code>filter</code> if non-null, and sorting the hits by the criteria in
  78                 /// <code>sort</code>.
  79                 ///
  80                 /// <p>Applications should usually call {@link
  81                 /// Searcher#Search(Query,Filter,Sort)} instead.
  82                 /// </summary>
  83                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  84                 public virtual TopFieldDocs Search(Query query, Filter filter, int n, Sort sort)
  85                 {
  86                         return Search(CreateWeight(query), filter, n, sort);
  87                 }
  88
  89                 /// <summary>Lower-level search API.
  90                 ///
  91                 /// <p>{@link HitCollector#Collect(int,float)} is called for every non-zero
  92                 /// scoring document.
  93                 ///
  94                 /// <p>Applications should only use this if they need <i>all</i> of the
  95                 /// matching documents.  The high-level search API ({@link
  96                 /// Searcher#Search(Query)}) is usually more efficient, as it skips
  97                 /// non-high-scoring hits.
  98                 /// <p>Note: The <code>score</code> passed to this method is a raw score.
  99                 /// In other words, the score will not necessarily be a float whose value is
 100                 /// between 0 and 1.
 101                 /// </summary>
 102                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 103                 public virtual void  Search(Query query, HitCollector results)
 104                 {
 105                         Search(query, (Filter) null, results);
 106                 }
 107
 108                 /// <summary>Lower-level search API.
 109                 ///
 110                 /// <p>{@link HitCollector#Collect(int,float)} is called for every non-zero
 111                 /// scoring document.
 112                 /// <br>HitCollector-based access to remote indexes is discouraged.
 113                 ///
 114                 /// <p>Applications should only use this if they need <i>all</i> of the
 115                 /// matching documents.  The high-level search API ({@link
 116                 /// Searcher#Search(Query)}) is usually more efficient, as it skips
 117                 /// non-high-scoring hits.
 118                 ///
 119                 /// </summary>
 120                 /// <param name="query">to match documents
 121                 /// </param>
 122                 /// <param name="filter">if non-null, a bitset used to eliminate some documents
 123                 /// </param>
 124                 /// <param name="results">to receive hits
 125                 /// </param>
 126                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 127                 public virtual void  Search(Query query, Filter filter, HitCollector results)
 128                 {
 129                         Search(CreateWeight(query), filter, results);
 130                 }
 131
 132                 /// <summary>Expert: Low-level search implementation.  Finds the top <code>n</code>
 133                 /// hits for <code>query</code>, applying <code>filter</code> if non-null.
 134                 ///
 135                 /// <p>Called by {@link Hits}.
 136                 ///
 137                 /// <p>Applications should usually call {@link Searcher#Search(Query)} or
 138                 /// {@link Searcher#Search(Query,Filter)} instead.
 139                 /// </summary>
 140                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 141                 public virtual TopDocs Search(Query query, Filter filter, int n)
 142                 {
 143                         return Search(CreateWeight(query), filter, n);
 144                 }
 145
 146                 /// <summary>Returns an Explanation that describes how <code>doc</code> scored against
 147                 /// <code>query</code>.
 148                 ///
 149                 /// <p>This is intended to be used in developing Similarity implementations,
 150                 /// and, for good performance, should not be displayed with every hit.
 151                 /// Computing an explanation is as expensive as executing the query over the
 152                 /// entire index.
 153                 /// </summary>
 154                 public virtual Explanation Explain(Query query, int doc)
 155                 {
 156                         return Explain(CreateWeight(query), doc);
 157                 }
 158
 159                 /// <summary>The Similarity implementation used by this searcher. </summary>
 160                 private Similarity similarity;
 161
 162                 /// <summary>Expert: Set the Similarity implementation used by this Searcher.
 163                 ///
 164                 /// </summary>
 165                 /// <seealso cref="Similarity.SetDefault(Similarity)">
 166                 /// </seealso>
 167                 public virtual void  SetSimilarity(Similarity similarity)
 168                 {
 169                         this.similarity = similarity;
 170                 }
 171
 172                 /// <summary>Expert: Return the Similarity implementation used by this Searcher.
 173                 ///
 174                 /// <p>This defaults to the current value of {@link Similarity#GetDefault()}.
 175                 /// </summary>
 176                 public virtual Similarity GetSimilarity()
 177                 {
 178                         return this.similarity;
 179                 }
 180
 181                 /// <summary> creates a weight for <code>query</code></summary>
 182                 /// <returns> new weight
 183                 /// </returns>
 184                 protected internal virtual Weight CreateWeight(Query query)
 185                 {
 186                         return query.Weight(this);
 187                 }
 188
 189                 // inherit javadoc
 190                 public virtual int[] DocFreqs(Term[] terms)
 191                 {
 192                         int[] result = new int[terms.Length];
 193                         for (int i = 0; i < terms.Length; i++)
 194                         {
 195                                 result[i] = DocFreq(terms[i]);
 196                         }
 197                         return result;
 198                 }
 199
 200                 /* The following abstract methods were added as a workaround for GCJ bug #15411.
 201                 * http://gcc.gnu.org/bugzilla/show_bug.cgi?id=15411
 202                 */
 203                 abstract public void  Search(Weight weight, Filter filter, HitCollector results);
 204                 abstract public void  Close();
 205                 abstract public int DocFreq(Term term);
 206                 abstract public int MaxDoc();
 207                 abstract public TopDocs Search(Weight weight, Filter filter, int n);
 208                 abstract public Document Doc(int i);
 209                 abstract public Query Rewrite(Query query);
 210                 abstract public Explanation Explain(Weight weight, int doc);
 211                 abstract public TopFieldDocs Search(Weight weight, Filter filter, int n, Sort sort);
 212                 /* End patch for GCJ bug #15411. */
 213         }
 214 }