mcs/tools/monkeydoc/Lucene.Net/Lucene.Net/Search/Searchable.cs

   1 /*
   2  * Licensed to the Apache Software Foundation (ASF) under one or more
   3  * contributor license agreements.  See the NOTICE file distributed with
   4  * this work for additional information regarding copyright ownership.
   5  * The ASF licenses this file to You under the Apache License, Version 2.0
   6  * (the "License"); you may not use this file except in compliance with
   7  * the License.  You may obtain a copy of the License at
   8  *
   9  * http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 using System;
  19
  20 using Document = Mono.Lucene.Net.Documents.Document;
  21 using FieldSelector = Mono.Lucene.Net.Documents.FieldSelector;
  22 using CorruptIndexException = Mono.Lucene.Net.Index.CorruptIndexException;
  23 using Term = Mono.Lucene.Net.Index.Term;
  24
  25 namespace Mono.Lucene.Net.Search
  26 {
  27
  28         /// <summary> The interface for search implementations.
  29         ///
  30         /// <p/>
  31         /// Searchable is the abstract network protocol for searching. Implementations
  32         /// provide search over a single index, over multiple indices, and over indices
  33         /// on remote servers.
  34         ///
  35         /// <p/>
  36         /// Queries, filters and sort criteria are designed to be compact so that they
  37         /// may be efficiently passed to a remote index, with only the top-scoring hits
  38         /// being returned, rather than every matching hit.
  39         ///
  40         /// <b>NOTE:</b> this interface is kept public for convenience. Since it is not
  41         /// expected to be implemented directly, it may be changed unexpectedly between
  42         /// releases.
  43         /// </summary>
  44         public interface Searchable
  45         {
  46
  47                 /// <summary>Lower-level search API.
  48                 ///
  49                 /// <p/>{@link HitCollector#Collect(int,float)} is called for every non-zero
  50                 /// scoring document.
  51                 /// <br/>HitCollector-based access to remote indexes is discouraged.
  52                 ///
  53                 /// <p/>Applications should only use this if they need <i>all</i> of the
  54                 /// matching documents.  The high-level search API ({@link
  55                 /// Searcher#Search(Query)}) is usually more efficient, as it skips
  56                 /// non-high-scoring hits.
  57                 ///
  58                 /// </summary>
  59                 /// <param name="weight">to match documents
  60                 /// </param>
  61                 /// <param name="filter">if non-null, used to permit documents to be collected.
  62                 /// </param>
  63                 /// <param name="results">to receive hits
  64                 /// </param>
  65                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  66                 /// <deprecated> use {@link #Search(Weight, Filter, Collector)} instead.
  67                 /// </deprecated>
  68         [Obsolete("use Search(Weight, Filter, Collector) instead.")]
  69                 void  Search(Weight weight, Filter filter, HitCollector results);
  70
  71                 /// <summary> Lower-level search API.
  72                 ///
  73                 /// <p/>
  74                 /// {@link Collector#Collect(int)} is called for every document. <br/>
  75                 /// Collector-based access to remote indexes is discouraged.
  76                 ///
  77                 /// <p/>
  78                 /// Applications should only use this if they need <i>all</i> of the matching
  79                 /// documents. The high-level search API ({@link Searcher#Search(Query)}) is
  80                 /// usually more efficient, as it skips non-high-scoring hits.
  81                 ///
  82                 /// </summary>
  83                 /// <param name="weight">to match documents
  84                 /// </param>
  85                 /// <param name="filter">if non-null, used to permit documents to be collected.
  86                 /// </param>
  87                 /// <param name="collector">to receive hits
  88                 /// </param>
  89                 /// <throws>  BooleanQuery.TooManyClauses </throws>
  90                 void  Search(Weight weight, Filter filter, Collector collector);
  91
  92                 /// <summary>Frees resources associated with this Searcher.
  93                 /// Be careful not to call this method while you are still using objects
  94                 /// like {@link Hits}.
  95                 /// </summary>
  96                 void  Close();
  97
  98                 /// <summary>Expert: Returns the number of documents containing <code>term</code>.
  99                 /// Called by search code to compute term weights.
 100                 /// </summary>
 101                 /// <seealso cref="Mono.Lucene.Net.Index.IndexReader.DocFreq(Term)">
 102                 /// </seealso>
 103                 int DocFreq(Term term);
 104
 105                 /// <summary>Expert: For each term in the terms array, calculates the number of
 106                 /// documents containing <code>term</code>. Returns an array with these
 107                 /// document frequencies. Used to minimize number of remote calls.
 108                 /// </summary>
 109                 int[] DocFreqs(Term[] terms);
 110
 111                 /// <summary>Expert: Returns one greater than the largest possible document number.
 112                 /// Called by search code to compute term weights.
 113                 /// </summary>
 114                 /// <seealso cref="Mono.Lucene.Net.Index.IndexReader.MaxDoc()">
 115                 /// </seealso>
 116                 int MaxDoc();
 117
 118                 /// <summary>Expert: Low-level search implementation.  Finds the top <code>n</code>
 119                 /// hits for <code>query</code>, applying <code>filter</code> if non-null.
 120                 ///
 121                 /// <p/>Called by {@link Hits}.
 122                 ///
 123                 /// <p/>Applications should usually call {@link Searcher#Search(Query)} or
 124                 /// {@link Searcher#Search(Query,Filter)} instead.
 125                 /// </summary>
 126                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 127                 TopDocs Search(Weight weight, Filter filter, int n);
 128
 129                 /// <summary>Expert: Returns the stored fields of document <code>i</code>.
 130                 /// Called by {@link HitCollector} implementations.
 131                 /// </summary>
 132                 /// <seealso cref="Mono.Lucene.Net.Index.IndexReader.Document(int)">
 133                 /// </seealso>
 134                 /// <throws>  CorruptIndexException if the index is corrupt </throws>
 135                 /// <throws>  IOException if there is a low-level IO error </throws>
 136                 Document Doc(int i);
 137
 138                 /// <summary> Get the {@link Mono.Lucene.Net.Documents.Document} at the <code>n</code><sup>th</sup> position. The {@link Mono.Lucene.Net.Documents.FieldSelector}
 139                 /// may be used to determine what {@link Mono.Lucene.Net.Documents.Field}s to load and how they should be loaded.
 140                 ///
 141                 /// <b>NOTE:</b> If the underlying Reader (more specifically, the underlying <code>FieldsReader</code>) is closed before the lazy {@link Mono.Lucene.Net.Documents.Field} is
 142                 /// loaded an exception may be thrown.  If you want the value of a lazy {@link Mono.Lucene.Net.Documents.Field} to be available after closing you must
 143                 /// explicitly load it or fetch the Document again with a new loader.
 144                 ///
 145                 ///
 146                 /// </summary>
 147                 /// <param name="n">Get the document at the <code>n</code><sup>th</sup> position
 148                 /// </param>
 149                 /// <param name="fieldSelector">The {@link Mono.Lucene.Net.Documents.FieldSelector} to use to determine what Fields should be loaded on the Document.  May be null, in which case all Fields will be loaded.
 150                 /// </param>
 151                 /// <returns> The stored fields of the {@link Mono.Lucene.Net.Documents.Document} at the nth position
 152                 /// </returns>
 153                 /// <throws>  CorruptIndexException if the index is corrupt </throws>
 154                 /// <throws>  IOException if there is a low-level IO error </throws>
 155                 /// <summary>
 156                 /// </summary>
 157                 /// <seealso cref="Mono.Lucene.Net.Index.IndexReader.Document(int, FieldSelector)">
 158                 /// </seealso>
 159                 /// <seealso cref="Mono.Lucene.Net.Documents.Fieldable">
 160                 /// </seealso>
 161                 /// <seealso cref="Mono.Lucene.Net.Documents.FieldSelector">
 162                 /// </seealso>
 163                 /// <seealso cref="Mono.Lucene.Net.Documents.SetBasedFieldSelector">
 164                 /// </seealso>
 165                 /// <seealso cref="Mono.Lucene.Net.Documents.LoadFirstFieldSelector">
 166                 /// </seealso>
 167                 Document Doc(int n, FieldSelector fieldSelector);
 168
 169                 /// <summary>Expert: called to re-write queries into primitive queries.</summary>
 170                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 171                 Query Rewrite(Query query);
 172
 173                 /// <summary>Expert: low-level implementation method
 174                 /// Returns an Explanation that describes how <code>doc</code> scored against
 175                 /// <code>weight</code>.
 176                 ///
 177                 /// <p/>This is intended to be used in developing Similarity implementations,
 178                 /// and, for good performance, should not be displayed with every hit.
 179                 /// Computing an explanation is as expensive as executing the query over the
 180                 /// entire index.
 181                 /// <p/>Applications should call {@link Searcher#Explain(Query, int)}.
 182                 /// </summary>
 183                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 184                 Explanation Explain(Weight weight, int doc);
 185
 186                 /// <summary>Expert: Low-level search implementation with arbitrary sorting.  Finds
 187                 /// the top <code>n</code> hits for <code>query</code>, applying
 188                 /// <code>filter</code> if non-null, and sorting the hits by the criteria in
 189                 /// <code>sort</code>.
 190                 ///
 191                 /// <p/>Applications should usually call
 192                 /// {@link Searcher#Search(Query,Filter,int,Sort)} instead.
 193                 ///
 194                 /// </summary>
 195                 /// <throws>  BooleanQuery.TooManyClauses </throws>
 196                 TopFieldDocs Search(Weight weight, Filter filter, int n, Sort sort);
 197         }
 198 }