Home » lucene-3.0.1-src » org.apache » lucene » search » function » [javadoc | source]

    1   package org.apache.lucene.search.function;
    2   
    3   /**
    4    * Licensed to the Apache Software Foundation (ASF) under one or more
    5    * contributor license agreements.  See the NOTICE file distributed with
    6    * this work for additional information regarding copyright ownership.
    7    * The ASF licenses this file to You under the Apache License, Version 2.0
    8    * (the "License"); you may not use this file except in compliance with
    9    * the License.  You may obtain a copy of the License at
   10    *
   11    *     http://www.apache.org/licenses/LICENSE-2.0
   12    *
   13    * Unless required by applicable law or agreed to in writing, software
   14    * distributed under the License is distributed on an "AS IS" BASIS,
   15    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   16    * See the License for the specific language governing permissions and
   17    * limitations under the License.
   18    */
   19   
   20   /**
   21    * A query that scores each document as the value of the numeric input field.
   22    * <p> 
   23    * The query matches all documents, and scores each document according to the numeric 
   24    * value of that field. 
   25    * <p>
   26    * It is assumed, and expected, that:
   27    * <ul>
   28    *  <li>The field used here is indexed, and has exactly 
   29    *      one token in every scored document.</li> 
   30    *  <li>Best if this field is un_tokenized.</li>
   31    *  <li>That token is parseable to the selected type.</li>
   32    * </ul>
   33    * <p>  
   34    * Combining this query in a FunctionQuery allows much freedom in affecting document scores.
   35    * Note, that with this freedom comes responsibility: it is more than likely that the
   36    * default Lucene scoring is superior in quality to scoring modified as explained here.
   37    * However, in some cases, and certainly for research experiments, this capability may turn useful.
   38    * <p>
   39    * When constructing this query, select the appropriate type. That type should match the data stored in the
   40    * field. So in fact the "right" type should be selected before indexing. Type selection
   41    * has effect on the RAM usage: 
   42    * <ul>
   43    *   <li>{@link Type#BYTE} consumes 1 * maxDocs bytes.</li>
   44    *   <li>{@link Type#SHORT} consumes 2 * maxDocs bytes.</li>
   45    *   <li>{@link Type#INT} consumes 4 * maxDocs bytes.</li>
   46    *   <li>{@link Type#FLOAT} consumes 8 * maxDocs bytes.</li>
   47    * </ul>
   48    * <p>
   49    * <b>Caching:</b>
   50    * Values for the numeric field are loaded once and cached in memory for further use with the same IndexReader. 
   51    * To take advantage of this, it is extremely important to reuse index-readers or index-searchers, 
   52    * otherwise, for instance if for each query a new index reader is opened, large penalties would be 
   53    * paid for loading the field values into memory over and over again!
   54    * 
   55    * <p><font color="#FF0000">
   56    * WARNING: The status of the <b>search.function</b> package is experimental. 
   57    * The APIs introduced here might change in the future and will not be 
   58    * supported anymore in such a case.</font>
   59    */
   60   public class FieldScoreQuery extends ValueSourceQuery {
   61   
   62     /**
   63      * Type of score field, indicating how field values are interpreted/parsed.  
   64      * <p>
   65      * The type selected at search search time should match the data stored in the field. 
   66      * Different types have different RAM requirements: 
   67      * <ul>
   68      *   <li>{@link #BYTE} consumes 1 * maxDocs bytes.</li>
   69      *   <li>{@link #SHORT} consumes 2 * maxDocs bytes.</li>
   70      *   <li>{@link #INT} consumes 4 * maxDocs bytes.</li>
   71      *   <li>{@link #FLOAT} consumes 8 * maxDocs bytes.</li>
   72      * </ul>
   73      */
   74     public static class Type {
   75       
   76       /** field values are interpreted as numeric byte values. */
   77       public static final Type BYTE = new Type("byte"); 
   78   
   79       /** field values are interpreted as numeric short values. */
   80       public static final Type SHORT = new Type("short"); 
   81   
   82       /** field values are interpreted as numeric int values. */
   83       public static final Type INT = new Type("int"); 
   84   
   85       /** field values are interpreted as numeric float values. */
   86       public static final Type FLOAT = new Type("float"); 
   87   
   88       private String typeName;
   89       private Type (String name) {
   90         this.typeName = name;
   91       }
   92       /*(non-Javadoc) @see java.lang.Object#toString() */
   93       @Override
   94       public String toString() {
   95         return getClass().getName()+"::"+typeName;
   96       }
   97     }
   98     
   99     /**
  100      * Create a FieldScoreQuery - a query that scores each document as the value of the numeric input field.
  101      * <p>
  102      * The <code>type</code> param tells how to parse the field string values into a numeric score value.
  103      * @param field the numeric field to be used.
  104      * @param type the type of the field: either
  105      * {@link Type#BYTE}, {@link Type#SHORT}, {@link Type#INT}, or {@link Type#FLOAT}. 
  106      */
  107     public FieldScoreQuery(String field, Type type) {
  108       super(getValueSource(field,type));
  109     }
  110   
  111     // create the appropriate (cached) field value source.  
  112     private static ValueSource getValueSource(String field, Type type) {
  113       if (type == Type.BYTE) {
  114         return new ByteFieldSource(field);
  115       }
  116       if (type == Type.SHORT) {
  117         return new ShortFieldSource(field);
  118       }
  119       if (type == Type.INT) {
  120         return new IntFieldSource(field);
  121       }
  122       if (type == Type.FLOAT) {
  123         return new FloatFieldSource(field);
  124       }
  125       throw new IllegalArgumentException(type+" is not a known Field Score Query Type!");
  126     }
  127   
  128   }

Home » lucene-3.0.1-src » org.apache » lucene » search » function » [javadoc | source]