beagled/Lucene.Net/Search/Searchable.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 IndexReader = Lucene.Net.Index.IndexReader;
  20 using Term = Lucene.Net.Index.Term;
  21
  22 namespace Lucene.Net.Search
  23 {
  24
  25         /// <summary>The interface for search implementations.
  26         ///
  27         /// <p>Searchable is the abstract network protocol for searching.
  28         /// Implementations provide search over a single index, over multiple
  29         /// indices, and over indices on remote servers.
  30         ///
  31         /// <p>Queries, filters and sort criteria are designed to be compact so that
  32         /// they may be efficiently passed to a remote index, with only the top-scoring
  33         /// hits being returned, rather than every non-zero scoring hit.
  34         /// </summary>
  35
  36     public interface Searchable
  37     {
  38         /// <summary>Lower-level search API.
  39         ///
  40         /// <p>{@link HitCollector#Collect(int,float)} is called for every non-zero
  41         /// scoring document.
  42         /// <br>HitCollector-based access to remote indexes is discouraged.
  43         ///
  44         /// <p>Applications should only use this if they need <i>all</i> of the
  45         /// matching documents.  The high-level search API ({@link
  46         /// Searcher#Search(Query)}) is usually more efficient, as it skips
  47         /// non-high-scoring hits.
  48         ///
  49         /// </summary>
  50         /// <param name="query">to match documents
  51         /// </param>
  52         /// <param name="filter">if non-null, a bitset used to eliminate some documents
  53         /// </param>
  54         /// <param name="results">to receive hits
  55         /// </param>
  56         /// <throws>  BooleanQuery.TooManyClauses </throws>
  57         /// <summary>
  58         /// </summary>
  59         /// <deprecated>
  60         /// </deprecated>
  61         void  Search(Query query, Filter filter, HitCollector results);
  62
  63         /// <summary>Expert: Low-level search implementation.
  64         /// Identical to {@link #Search(Query, Filter, HitCollector)}, but takes
  65         /// a Weight instead of a query.
  66         /// </summary>
  67         void  Search(Weight weight, Filter filter, HitCollector results);
  68
  69         /// <summary>Frees resources associated with this Searcher.
  70         /// Be careful not to call this method while you are still using objects
  71         /// like {@link Hits}.
  72         /// </summary>
  73         void  Close();
  74
  75         /// <summary>Expert: Returns the number of documents containing <code>term</code>.
  76         /// Called by search code to compute term weights.
  77         /// </summary>
  78         /// <seealso cref="IndexReader#docFreq(Term)">
  79         /// </seealso>
  80         int DocFreq(Term term);
  81
  82         /// <summary>Expert: For each term in the terms array, calculates the number of
  83         /// documents containing <code>term</code>. Returns an array with these
  84         /// document frequencies. Used to minimize number of remote calls.
  85         /// </summary>
  86         int[] DocFreqs(Term[] terms);
  87
  88         /// <summary>Expert: Returns one greater than the largest possible document number.
  89         /// Called by search code to compute term weights.
  90         /// </summary>
  91         /// <seealso cref="IndexReader#maxDoc()">
  92         /// </seealso>
  93         int MaxDoc();
  94
  95         /// <summary>Expert: Low-level search implementation.  Finds the top <code>n</code>
  96         /// hits for <code>query</code>, applying <code>filter</code> if non-null.
  97         ///
  98         /// <p>Called by {@link Hits}.
  99         ///
 100         /// <p>Applications should usually call {@link Searcher#Search(Query)} or
 101         /// {@link Searcher#Search(Query,Filter)} instead.
 102         /// </summary>
 103         /// <throws>  BooleanQuery.TooManyClauses </throws>
 104         /// <summary>
 105         /// </summary>
 106         /// <deprecated>
 107         /// </deprecated>
 108         TopDocs Search(Query query, Filter filter, int n);
 109
 110         /// <summary>Expert: Low-level search implementation.
 111         /// Identical to {@link #Search(Query, Filter, int)}, but takes
 112         /// a Weight instead of a query.
 113         /// </summary>
 114         TopDocs Search(Weight weight, Filter filter, int n);
 115
 116         /// <summary>Expert: Returns the stored fields of document <code>i</code>.
 117         /// Called by {@link HitCollector} implementations.
 118         /// </summary>
 119         /// <seealso cref="IndexReader#document(int)">
 120         /// </seealso>
 121         Document Doc(int i);
 122
 123         /// <summary>Expert: called to re-write queries into primitive queries.</summary>
 124         /// <throws>  BooleanQuery.TooManyClauses </throws>
 125         Query Rewrite(Query query);
 126
 127         /// <summary>Returns an Explanation that describes how <code>doc</code> scored against
 128         /// <code>query</code>.
 129         ///
 130         /// <p>This is intended to be used in developing Similarity implementations,
 131         /// and, for good performance, should not be displayed with every hit.
 132         /// Computing an explanation is as expensive as executing the query over the
 133         /// entire index.
 134         /// </summary>
 135         /// <throws>  BooleanQuery.TooManyClauses </throws>
 136         Explanation Explain(Query query, int doc);
 137
 138         /// <summary> Identical to {@link #Search(Query, Filter, HitCollector)}, but takes
 139         /// a Weight instead of a query.
 140         /// </summary>
 141         Explanation Explain(Weight weight, int doc);
 142
 143         /// <summary>Expert: Low-level search implementation with arbitrary sorting.  Finds
 144         /// the top <code>n</code> hits for <code>query</code>, applying
 145         /// <code>filter</code> if non-null, and sorting the hits by the criteria in
 146         /// <code>sort</code>.
 147         ///
 148         /// <p>Applications should usually call {@link
 149         /// Searcher#Search(Query,Filter,Sort)} instead.
 150         /// </summary>
 151         /// <throws>  BooleanQuery.TooManyClauses </throws>
 152         /// <summary>
 153         /// </summary>
 154         /// <deprecated>
 155         /// </deprecated>
 156         TopFieldDocs Search(Query query, Filter filter, int n, Sort sort);
 157
 158         /// <summary>Expert: Low-level search implementation.
 159         /// Identical to {@link #Search(Query, Filter, int, Sort)}, but takes
 160         /// a Weight instead of a query.
 161         /// </summary>
 162         TopFieldDocs Search(Weight weight, Filter filter, int n, Sort sort);
 163     }
 164 }