FieldCache.java
001 package gate.creole.annic.apache.lucene.search;
002 
003 /**
004  * Copyright 2004 The Apache Software Foundation
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 
019 import gate.creole.annic.apache.lucene.index.IndexReader;
020 import java.io.IOException;
021 
022 /**
023  * Expert: Maintains caches of term values.
024  *
025  <p>Created: May 19, 2004 11:13:14 AM
026  *
027  @author  Tim Jones (Nacimiento Software)
028  @since   lucene 1.4
029  @version $Id: FieldCache.java 529 2004-10-05 11:55:26Z niraj $
030  */
031 @SuppressWarnings("rawtypes")
032 public interface FieldCache {
033 
034   /** Indicator for StringIndex values in the cache. */
035   // NOTE: the value assigned to this constant must not be
036   // the same as any of those in SortField!!
037   public static final int STRING_INDEX = -1;
038 
039 
040   /** Expert: Stores term text values and document ordering data. */
041   public static class StringIndex {
042 
043     /** All the term values, in natural order. */
044     public final String[] lookup;
045 
046     /** For each document, an index into the lookup array. */
047     public final int[] order;
048 
049     /** Creates one of these objects */
050     public StringIndex (int[] values, String[] lookup) {
051       this.order = values;
052       this.lookup = lookup;
053     }
054   }
055 
056 
057   /** Expert: The cache used internally by sorting and range query classes. */
058   public static FieldCache DEFAULT = new FieldCacheImpl();
059 
060 
061   /** Checks the internal cache for an appropriate entry, and if none is
062    * found, reads the terms in <code>field</code> as integers and returns an array
063    * of size <code>reader.maxDoc()</code> of the value each document
064    * has in the given field.
065    @param reader  Used to get field values.
066    @param field   Which field contains the integers.
067    @return The values in the given field for each document.
068    @throws IOException  If any error occurs.
069    */
070   public int[] getInts (IndexReader reader, String field)
071   throws IOException;
072 
073   /** Checks the internal cache for an appropriate entry, and if
074    * none is found, reads the terms in <code>field</code> as floats and returns an array
075    * of size <code>reader.maxDoc()</code> of the value each document
076    * has in the given field.
077    @param reader  Used to get field values.
078    @param field   Which field contains the floats.
079    @return The values in the given field for each document.
080    @throws IOException  If any error occurs.
081    */
082   public float[] getFloats (IndexReader reader, String field)
083   throws IOException;
084 
085   /** Checks the internal cache for an appropriate entry, and if none
086    * is found, reads the term values in <code>field</code> and returns an array
087    * of size <code>reader.maxDoc()</code> containing the value each document
088    * has in the given field.
089    @param reader  Used to get field values.
090    @param field   Which field contains the strings.
091    @return The values in the given field for each document.
092    @throws IOException  If any error occurs.
093    */
094   public String[] getStrings (IndexReader reader, String field)
095   throws IOException;
096 
097   /** Checks the internal cache for an appropriate entry, and if none
098    * is found reads the term values in <code>field</code> and returns
099    * an array of them in natural order, along with an array telling
100    * which element in the term array each document uses.
101    @param reader  Used to get field values.
102    @param field   Which field contains the strings.
103    @return Array of terms and index into the array for each document.
104    @throws IOException  If any error occurs.
105    */
106   public StringIndex getStringIndex (IndexReader reader, String field)
107   throws IOException;
108 
109   /** Checks the internal cache for an appropriate entry, and if
110    * none is found reads <code>field</code> to see if it contains integers, floats
111    * or strings, and then calls one of the other methods in this class to get the
112    * values.  For string values, a StringIndex is returned.  After
113    * calling this method, there is an entry in the cache for both
114    * type <code>AUTO</code> and the actual found type.
115    @param reader  Used to get field values.
116    @param field   Which field contains the values.
117    @return int[], float[] or StringIndex.
118    @throws IOException  If any error occurs.
119    */
120   public Object getAuto (IndexReader reader, String field)
121   throws IOException;
122 
123   /** Checks the internal cache for an appropriate entry, and if none
124    * is found reads the terms out of <code>field</code> and calls the given SortComparator
125    * to get the sort values.  A hit in the cache will happen if <code>reader</code>,
126    <code>field</code>, and <code>comparator</code> are the same (using <code>equals()</code>)
127    * as a previous call to this method.
128    @param reader  Used to get field values.
129    @param field   Which field contains the values.
130    @param comparator Used to convert terms into something to sort by.
131    @return Array of sort objects, one for each document.
132    @throws IOException  If any error occurs.
133    */
134   public Comparable[] getCustom (IndexReader reader, String field, SortComparator comparator)
135   throws IOException;
136 }