mcs/tools/monkeydoc/Lucene.Net/Lucene.Net/Search/Function/FieldScoreQuery.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 namespace Mono.Lucene.Net.Search.Function
  21 {
  22
  23         /// <summary> A query that scores each document as the value of the numeric input field.
  24         /// <p/>
  25         /// The query matches all documents, and scores each document according to the numeric
  26         /// value of that field.
  27         /// <p/>
  28         /// It is assumed, and expected, that:
  29         /// <ul>
  30         /// <li>The field used here is indexed, and has exactly
  31         /// one token in every scored document.</li>
  32         /// <li>Best if this field is un_tokenized.</li>
  33         /// <li>That token is parsable to the selected type.</li>
  34         /// </ul>
  35         /// <p/>
  36         /// Combining this query in a FunctionQuery allows much freedom in affecting document scores.
  37         /// Note, that with this freedom comes responsibility: it is more than likely that the
  38         /// default Lucene scoring is superior in quality to scoring modified as explained here.
  39         /// However, in some cases, and certainly for research experiments, this capability may turn useful.
  40         /// <p/>
  41         /// When contructing this query, select the appropriate type. That type should match the data stored in the
  42         /// field. So in fact the "right" type should be selected before indexing. Type selection
  43         /// has effect on the RAM usage:
  44         /// <ul>
  45         /// <li>{@link Type#BYTE} consumes 1 * maxDocs bytes.</li>
  46         /// <li>{@link Type#SHORT} consumes 2 * maxDocs bytes.</li>
  47         /// <li>{@link Type#INT} consumes 4 * maxDocs bytes.</li>
  48         /// <li>{@link Type#FLOAT} consumes 8 * maxDocs bytes.</li>
  49         /// </ul>
  50         /// <p/>
  51         /// <b>Caching:</b>
  52         /// Values for the numeric field are loaded once and cached in memory for further use with the same IndexReader.
  53         /// To take advantage of this, it is extremely important to reuse index-readers or index-searchers,
  54         /// otherwise, for instance if for each query a new index reader is opened, large penalties would be
  55         /// paid for loading the field values into memory over and over again!
  56         ///
  57         /// <p/><font color="#FF0000">
  58         /// WARNING: The status of the <b>Search.Function</b> package is experimental.
  59         /// The APIs introduced here might change in the future and will not be
  60         /// supported anymore in such a case.</font>
  61         /// </summary>
  62         [Serializable]
  63         public class FieldScoreQuery:ValueSourceQuery
  64         {
  65
  66                 /// <summary> Type of score field, indicating how field values are interpreted/parsed.
  67                 /// <p/>
  68                 /// The type selected at search search time should match the data stored in the field.
  69                 /// Different types have different RAM requirements:
  70                 /// <ul>
  71                 /// <li>{@link #BYTE} consumes 1 * maxDocs bytes.</li>
  72                 /// <li>{@link #SHORT} consumes 2 * maxDocs bytes.</li>
  73                 /// <li>{@link #INT} consumes 4 * maxDocs bytes.</li>
  74                 /// <li>{@link #FLOAT} consumes 8 * maxDocs bytes.</li>
  75                 /// </ul>
  76                 /// </summary>
  77                 public class Type
  78                 {
  79
  80                         /// <summary>field values are interpreted as numeric byte values. </summary>
  81                         public static readonly Type BYTE = new Type("byte");
  82
  83                         /// <summary>field values are interpreted as numeric short values. </summary>
  84                         public static readonly Type SHORT = new Type("short");
  85
  86                         /// <summary>field values are interpreted as numeric int values. </summary>
  87                         public static readonly Type INT = new Type("int");
  88
  89                         /// <summary>field values are interpreted as numeric float values. </summary>
  90                         public static readonly Type FLOAT = new Type("float");
  91
  92                         private System.String typeName;
  93                         internal Type(System.String name)
  94                         {
  95                                 this.typeName = name;
  96                         }
  97                         /*(non-Javadoc) @see java.lang.Object#toString() */
  98                         public override System.String ToString()
  99                         {
 100                                 return GetType().FullName + "::" + typeName;
 101                         }
 102                 }
 103
 104                 /// <summary> Create a FieldScoreQuery - a query that scores each document as the value of the numeric input field.
 105                 /// <p/>
 106                 /// The <code>type</code> param tells how to parse the field string values into a numeric score value.
 107                 /// </summary>
 108                 /// <param name="field">the numeric field to be used.
 109                 /// </param>
 110                 /// <param name="type">the type of the field: either
 111                 /// {@link Type#BYTE}, {@link Type#SHORT}, {@link Type#INT}, or {@link Type#FLOAT}.
 112                 /// </param>
 113                 public FieldScoreQuery(System.String field, Type type):base(GetValueSource(field, type))
 114                 {
 115                 }
 116
 117                 // create the appropriate (cached) field value source.
 118                 private static ValueSource GetValueSource(System.String field, Type type)
 119                 {
 120                         if (type == Type.BYTE)
 121                         {
 122                                 return new ByteFieldSource(field);
 123                         }
 124                         if (type == Type.SHORT)
 125                         {
 126                                 return new ShortFieldSource(field);
 127                         }
 128                         if (type == Type.INT)
 129                         {
 130                                 return new IntFieldSource(field);
 131                         }
 132                         if (type == Type.FLOAT)
 133                         {
 134                                 return new FloatFieldSource(field);
 135                         }
 136                         throw new System.ArgumentException(type + " is not a known Field Score Query Type!");
 137                 }
 138         }
 139 }