lucene-java-3.4.0/lucene/src/java/org/apache/lucene/search/function/DocValues.java

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