1 package org.apache.lucene.search.function;
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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
20 import org.apache.lucene.search.Explanation;
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.
28 * @lucene.experimental
32 public abstract class DocValues {
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
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.
47 public abstract float floatVal(int doc);
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.
54 public int intVal(int doc) {
55 return (int) floatVal(doc);
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.
63 public long longVal(int doc) {
64 return (long) floatVal(doc);
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.
72 public double doubleVal(int doc) {
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.
81 public String strVal(int doc) {
82 return Float.toString(floatVal(doc));
86 * Return a string representation of a doc value, as required for Explanations.
88 public abstract String toString(int doc);
91 * Explain the scoring value for the input doc.
93 public Explanation explain(int doc) {
94 return new Explanation(floatVal(doc), toString(doc));
98 * Expert: for test purposes only, return the inner array of values, or null if not applicable.
100 * Allows tests to verify that loaded values are:
102 * <li>indeed cached/reused.</li>
103 * <li>stored in the expected size/type (byte/short/int/float).</li>
105 * Note: implementations of DocValues must override this method for
106 * these test elements to be tested, Otherwise the test would not fail, just
109 Object getInnerArray() {
110 throw new UnsupportedOperationException("this optional method is for test purposes only");
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() {
129 } catch (ArrayIndexOutOfBoundsException e) {
133 minVal = Float.isNaN(minVal) ? val : Math.min(minVal, val);
134 maxVal = Float.isNaN(maxVal) ? val : Math.max(maxVal, val);
138 avgVal = n == 0 ? Float.NaN : sum / n;
143 * Returns the minimum of all values or <code>Float.NaN</code> if this
144 * DocValues instance does not contain any value.
146 * This operation is optional
149 * @return the minimum of all values or <code>Float.NaN</code> if this
150 * DocValues instance does not contain any value.
152 public float getMinValue() {
158 * Returns the maximum of all values or <code>Float.NaN</code> if this
159 * DocValues instance does not contain any value.
161 * This operation is optional
164 * @return the maximum of all values or <code>Float.NaN</code> if this
165 * DocValues instance does not contain any value.
167 public float getMaxValue() {
173 * Returns the average of all values or <code>Float.NaN</code> if this
174 * DocValues instance does not contain any value. *
176 * This operation is optional
179 * @return the average of all values or <code>Float.NaN</code> if this
180 * DocValues instance does not contain any value
182 public float getAverageValue() {