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   import org.apache.lucene.search.Explanation;
   21   
   22   /**
   23    * Expert: represents field values as different types.
   24    * Normally created via a 
   25    * {@link org.apache.lucene.search.function.ValueSource ValueSuorce} 
   26    * for a particular field and reader.
   27    *
   28    * <p><font color="#FF0000">
   29    * WARNING: The status of the <b>search.function</b> package is experimental. 
   30    * The APIs introduced here might change in the future and will not be 
   31    * supported anymore in such a case.</font>
   32    * 
   33    *
   34    */
   35   public abstract class DocValues {
   36     /*
   37      * DocValues is distinct from ValueSource because
   38      * there needs to be an object created at query evaluation time that
   39      * is not referenced by the query itself because:
   40      * - Query objects should be MT safe
   41      * - For caching, Query objects are often used as keys... you don't
   42      *   want the Query carrying around big objects
   43      */
   44   
   45     /**
   46      * Return doc value as a float. 
   47      * <P>Mandatory: every DocValues implementation must implement at least this method. 
   48      * @param doc document whose float value is requested. 
   49      */
   50     public abstract float floatVal(int doc);
   51     
   52     /**
   53      * Return doc value as an int. 
   54      * <P>Optional: DocValues implementation can (but don't have to) override this method. 
   55      * @param doc document whose int value is requested.
   56      */
   57     public int intVal(int doc) { 
   58       return (int) floatVal(doc);
   59     }
   60     
   61     /**
   62      * Return doc value as a long. 
   63      * <P>Optional: DocValues implementation can (but don't have to) override this method. 
   64      * @param doc document whose long value is requested.
   65      */
   66     public long longVal(int doc) {
   67       return (long) floatVal(doc);
   68     }
   69   
   70     /**
   71      * Return doc value as a double. 
   72      * <P>Optional: DocValues implementation can (but don't have to) override this method. 
   73      * @param doc document whose double value is requested.
   74      */
   75     public double doubleVal(int doc) {
   76       return (double) floatVal(doc);
   77     }
   78     
   79     /**
   80      * Return doc value as a string. 
   81      * <P>Optional: DocValues implementation can (but don't have to) override this method. 
   82      * @param doc document whose string value is requested.
   83      */
   84     public String strVal(int doc) {
   85       return Float.toString(floatVal(doc));
   86     }
   87     
   88     /**
   89      * Return a string representation of a doc value, as required for Explanations.
   90      */
   91     public abstract String toString(int doc);
   92     
   93     /**
   94      * Explain the scoring value for the input doc.
   95      */
   96     public Explanation explain(int doc) {
   97       return new Explanation(floatVal(doc), toString(doc));
   98     }
   99     
  100     /**
  101      * Expert: for test purposes only, return the inner array of values, or null if not applicable.
  102      * <p>
  103      * Allows tests to verify that loaded values are:
  104      * <ol>
  105      *   <li>indeed cached/reused.</li>
  106      *   <li>stored in the expected size/type (byte/short/int/float).</li>
  107      * </ol>
  108      * Note: implementations of DocValues must override this method for 
  109      * these test elements to be tested, Otherwise the test would not fail, just 
  110      * print a warning.
  111      */
  112     Object getInnerArray() {
  113       throw new UnsupportedOperationException("this optional method is for test purposes only");
  114     }
  115   
  116     // --- some simple statistics on values
  117     private float minVal = Float.NaN;
  118     private float maxVal = Float.NaN;
  119     private float avgVal = Float.NaN;
  120     private boolean computed=false;
  121     // compute optional values
  122     private void compute() {
  123       if (computed) {
  124         return;
  125       }
  126       float sum = 0;
  127       int n = 0;
  128       while (true) {
  129         float val;
  130         try {
  131           val = floatVal(n);
  132         } catch (ArrayIndexOutOfBoundsException e) {
  133           break;
  134         }
  135         sum += val;
  136         minVal = Float.isNaN(minVal) ? val : Math.min(minVal, val);
  137         maxVal = Float.isNaN(maxVal) ? val : Math.max(maxVal, val);
  138         ++n;
  139       }
  140   
  141       avgVal = n == 0 ? Float.NaN : sum / n;
  142       computed = true;
  143     }
  144   
  145     /**
  146      * Returns the minimum of all values or <code>Float.NaN</code> if this
  147      * DocValues instance does not contain any value.
  148      * <p>
  149      * This operation is optional
  150      * </p>
  151      * 
  152      * @return the minimum of all values or <code>Float.NaN</code> if this
  153      *         DocValues instance does not contain any value.
  154      */
  155     public float getMinValue() {
  156       compute();
  157       return minVal;
  158     }
  159   
  160     /**
  161      * Returns the maximum of all values or <code>Float.NaN</code> if this
  162      * DocValues instance does not contain any value.
  163      * <p>
  164      * This operation is optional
  165      * </p>
  166      * 
  167      * @return the maximum of all values or <code>Float.NaN</code> if this
  168      *         DocValues instance does not contain any value.
  169      */
  170     public float getMaxValue() {
  171       compute();
  172       return maxVal;
  173     }
  174   
  175     /**
  176      * Returns the average of all values or <code>Float.NaN</code> if this
  177      * DocValues instance does not contain any value. *
  178      * <p>
  179      * This operation is optional
  180      * </p>
  181      * 
  182      * @return the average of all values or <code>Float.NaN</code> if this
  183      *         DocValues instance does not contain any value
  184      */
  185     public float getAverageValue() {
  186       compute();
  187       return avgVal;
  188     }
  189   
  190   }

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