lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/function/FieldCacheSource.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 java.io.IOException;
  21
  22 import org.apache.lucene.index.IndexReader;
  23 import org.apache.lucene.search.FieldCache;
  24
  25 /**
  26  * Expert: A base class for ValueSource implementations that retrieve values for
  27  * a single field from the {@link org.apache.lucene.search.FieldCache FieldCache}.
  28  * <p>
  29  * Fields used herein must be indexed (doesn't matter if these fields are stored or not).
  30  * <p>
  31  * It is assumed that each such indexed field is untokenized, or at least has a single token in a document.
  32  * For documents with multiple tokens of the same field, behavior is undefined (It is likely that current
  33  * code would use the value of one of these tokens, but this is not guaranteed).
  34  * <p>
  35  * Document with no tokens in this field are assigned the <code>Zero</code> value.
  36  *
  37  * @lucene.experimental
  38  *
  39  * <p><b>NOTE</b>: with the switch in 2.9 to segment-based
  40  * searching, if {@link #getValues} is invoked with a
  41  * composite (multi-segment) reader, this can easily cause
  42  * double RAM usage for the values in the FieldCache.  It's
  43  * best to switch your application to pass only atomic
  44  * (single segment) readers to this API.</p>
  45  */
  46 public abstract class FieldCacheSource extends ValueSource {
  47   private String field;
  48
  49   /**
  50    * Create a cached field source for the input field.
  51    */
  52   public FieldCacheSource(String field) {
  53     this.field=field;
  54   }
  55
  56   /* (non-Javadoc) @see org.apache.lucene.search.function.ValueSource#getValues(org.apache.lucene.index.IndexReader) */
  57   @Override
  58   public final DocValues getValues(IndexReader reader) throws IOException {
  59     return getCachedFieldValues(FieldCache.DEFAULT, field, reader);
  60   }
  61
  62   /* (non-Javadoc) @see org.apache.lucene.search.function.ValueSource#description() */
  63   @Override
  64   public String description() {
  65     return field;
  66   }
  67
  68   /**
  69    * Return cached DocValues for input field and reader.
  70    * @param cache FieldCache so that values of a field are loaded once per reader (RAM allowing)
  71    * @param field Field for which values are required.
  72    * @see ValueSource
  73    */
  74   public abstract DocValues getCachedFieldValues(FieldCache cache, String field, IndexReader reader) throws IOException;
  75
  76   /*(non-Javadoc) @see java.lang.Object#equals(java.lang.Object) */
  77   @Override
  78   public final boolean equals(Object o) {
  79     if (!(o instanceof FieldCacheSource)) {
  80       return false;
  81     }
  82     FieldCacheSource other = (FieldCacheSource) o;
  83     return
  84       this.field.equals(other.field) &&
  85       cachedFieldSourceEquals(other);
  86   }
  87
  88   /*(non-Javadoc) @see java.lang.Object#hashCode() */
  89   @Override
  90   public final int hashCode() {
  91     return
  92       field.hashCode() +
  93       cachedFieldSourceHashCode();
  94   }
  95
  96   /**
  97    * Check if equals to another {@link FieldCacheSource}, already knowing that cache and field are equal.
  98    * @see Object#equals(java.lang.Object)
  99    */
 100   public abstract boolean cachedFieldSourceEquals(FieldCacheSource other);
 101
 102   /**
 103    * Return a hash code of a {@link FieldCacheSource}, without the hash-codes of the field
 104    * and the cache (those are taken care of elsewhere).
 105    * @see Object#hashCode()
 106    */
 107   public abstract int cachedFieldSourceHashCode();
 108 }