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