## org.apache.lucene.search
Interface FieldCache

    public interface FieldCache

Expert: Maintains caches of term values.

Created: May 19, 2004 11:13:14 AM

Since:
  lucene 1.4
See Also:
  `FieldCacheSanityChecker`

Nested Class Summary
`static interface` `FieldCache.ByteParser` Interface to parse bytes from document fields.
`static class` `FieldCache.CacheEntry` EXPERT: A unique Identifier/Description for each item in the FieldCache.
`static class` `FieldCache.CreationPlaceholder`
`static interface` `FieldCache.DoubleParser` Interface to parse doubles from document fields.
`static interface` `FieldCache.FloatParser` Interface to parse floats from document fields.
`static interface` `FieldCache.IntParser` Interface to parse ints from document fields.
`static interface` `FieldCache.LongParser` Interface to parse long from document fields.
`static interface` `FieldCache.Parser` Marker interface as super-interface to all parsers.
`static interface` `FieldCache.ShortParser` Interface to parse shorts from document fields.
`static class` `FieldCache.StringIndex` Expert: Stores term text values and document ordering data.

Field Summary
`static FieldCache` `DEFAULT` Expert: The cache used internally by sorting and range query classes.
`static FieldCache.ByteParser` `DEFAULT_BYTE_PARSER` The default parser for byte values, which are encoded by `Byte.toString(byte)`
`static FieldCache.DoubleParser` `DEFAULT_DOUBLE_PARSER` The default parser for double values, which are encoded by `Double.toString(double)`
`static FieldCache.FloatParser` `DEFAULT_FLOAT_PARSER` The default parser for float values, which are encoded by `Float.toString(float)`
`static FieldCache.IntParser` `DEFAULT_INT_PARSER` The default parser for int values, which are encoded by `Integer.toString(int)`
`static FieldCache.LongParser` `DEFAULT_LONG_PARSER` The default parser for long values, which are encoded by `Long.toString(long)`
`static FieldCache.ShortParser` `DEFAULT_SHORT_PARSER` The default parser for short values, which are encoded by `Short.toString(short)`
`static FieldCache.DoubleParser` `NUMERIC_UTILS_DOUBLE_PARSER` A parser instance for double values encoded with `NumericUtils`, e.g.
`static FieldCache.FloatParser` `NUMERIC_UTILS_FLOAT_PARSER` A parser instance for float values encoded with `NumericUtils`, e.g.
`static FieldCache.IntParser` `NUMERIC_UTILS_INT_PARSER` A parser instance for int values encoded by `NumericUtils.intToPrefixCoded(int)`, e.g.
`static FieldCache.LongParser` `NUMERIC_UTILS_LONG_PARSER` A parser instance for long values encoded by `NumericUtils.longToPrefixCoded(long)`, e.g.
`static int` `STRING_INDEX` Indicator for StringIndex values in the cache.

Method Summary
`byte[]` `getBytes(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as a single byte and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`byte[]` `getBytes(IndexReader reader, String field, FieldCache.ByteParser parser)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as bytes and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`byte[]` `getBytes(IndexReader reader, String field, FieldCache.ByteParser parser, boolean setDocsWithField)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as bytes and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`FieldCache.CacheEntry[]` `getCacheEntries()` EXPERT: Generates an array of CacheEntry objects representing all items currently in the FieldCache.
`Bits` `getDocsWithField(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` and returns a bit set at the size of `reader.maxDoc()`, with turned on bits for each docid that does have a value for this field.
`double[]` `getDoubles(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`double[]` `getDoubles(IndexReader reader, String field, FieldCache.DoubleParser parser)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as doubles and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`double[]` `getDoubles(IndexReader reader, String field, FieldCache.DoubleParser parser, boolean setDocsWithField)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as doubles and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`float[]` `getFloats(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as floats and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`float[]` `getFloats(IndexReader reader, String field, FieldCache.FloatParser parser)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as floats and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`float[]` `getFloats(IndexReader reader, String field, FieldCache.FloatParser parser, boolean setDocsWithField)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as floats and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`PrintStream` `getInfoStream()` counterpart of `setInfoStream(PrintStream)`
`int[]` `getInts(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`int[]` `getInts(IndexReader reader, String field, FieldCache.IntParser parser)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`int[]` `getInts(IndexReader reader, String field, FieldCache.IntParser parser, boolean setDocsWithField)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`long[]` `getLongs(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as longs and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`long[]` `getLongs(IndexReader reader, String field, FieldCache.LongParser parser)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as longs and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`long[]` `getLongs(IndexReader reader, String field, FieldCache.LongParser parser, boolean setDocsWithField)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as longs and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`short[]` `getShorts(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as shorts and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`short[]` `getShorts(IndexReader reader, String field, FieldCache.ShortParser parser)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as shorts and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`short[]` `getShorts(IndexReader reader, String field, FieldCache.ShortParser parser, boolean setDocsWithField)` Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as shorts and returns an array of size `reader.maxDoc()` of the value each document has in the given field.
`FieldCache.StringIndex` `getStringIndex(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found reads the term values in `field` and returns an array of them in natural order, along with an array telling which element in the term array each document uses.
`String[]` `getStrings(IndexReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the term values in `field` and returns an array of size `reader.maxDoc()` containing the value each document has in the given field.
`void` `purge(IndexReader r)` Expert: drops all cache entries associated with this reader.
`void` `purgeAllCaches()` EXPERT: Instructs the FieldCache to forcibly expunge all entries from the underlying caches.
`void` `setInfoStream(PrintStream stream)` If non-null, FieldCacheImpl will warn whenever entries are created that are not sane according to `FieldCacheSanityChecker`.

Field Detail

### STRING_INDEX

    static final int STRING_INDEX

  Indicator for StringIndex values in the cache.

  See Also:
    Constant Field Values

### DEFAULT

    static final FieldCache DEFAULT

  Expert: The cache used internally by sorting and range query classes.

### DEFAULT_BYTE_PARSER

    static final FieldCache.ByteParser DEFAULT_BYTE_PARSER

  The default parser for byte values, which are encoded by `Byte.toString(byte)`

### DEFAULT_SHORT_PARSER

    static final FieldCache.ShortParser DEFAULT_SHORT_PARSER

  The default parser for short values, which are encoded by `Short.toString(short)`

### DEFAULT_INT_PARSER

    static final FieldCache.IntParser DEFAULT_INT_PARSER

  The default parser for int values, which are encoded by `Integer.toString(int)`

### DEFAULT_FLOAT_PARSER

    static final FieldCache.FloatParser DEFAULT_FLOAT_PARSER

  The default parser for float values, which are encoded by `Float.toString(float)`

### DEFAULT_LONG_PARSER

    static final FieldCache.LongParser DEFAULT_LONG_PARSER

  The default parser for long values, which are encoded by `Long.toString(long)`

### DEFAULT_DOUBLE_PARSER

    static final FieldCache.DoubleParser DEFAULT_DOUBLE_PARSER

  The default parser for double values, which are encoded by `Double.toString(double)`

### NUMERIC_UTILS_INT_PARSER

    static final FieldCache.IntParser NUMERIC_UTILS_INT_PARSER

  A parser instance for int values encoded by `NumericUtils.intToPrefixCoded(int)`, e.g. when indexed via `NumericField`/`NumericTokenStream`.

### NUMERIC_UTILS_FLOAT_PARSER

    static final FieldCache.FloatParser NUMERIC_UTILS_FLOAT_PARSER

  A parser instance for float values encoded with `NumericUtils`, e.g. when indexed via `NumericField`/`NumericTokenStream`.

### NUMERIC_UTILS_LONG_PARSER

    static final FieldCache.LongParser NUMERIC_UTILS_LONG_PARSER

  A parser instance for long values encoded by `NumericUtils.longToPrefixCoded(long)`, e.g. when indexed via `NumericField`/`NumericTokenStream`.

### NUMERIC_UTILS_DOUBLE_PARSER

    static final FieldCache.DoubleParser NUMERIC_UTILS_DOUBLE_PARSER

  A parser instance for double values encoded with `NumericUtils`, e.g. when indexed via `NumericField`/`NumericTokenStream`.

Method Detail

### getDocsWithField

    Bits getDocsWithField(IndexReader reader,
                          String field)
                          throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` and returns a bit set at the size of `reader.maxDoc()`, with turned on bits for each docid that does have a value for this field.

  Throws:
    `IOException`

### getBytes

    byte[] getBytes(IndexReader reader,
                    String field)
                    throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as a single byte and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the single byte values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getBytes

    byte[] getBytes(IndexReader reader,
                    String field,
                    FieldCache.ByteParser parser)
                    throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as bytes and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the bytes.
    `parser` - Computes byte for string values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getBytes

    byte[] getBytes(IndexReader reader,
                    String field,
                    FieldCache.ByteParser parser,
                    boolean setDocsWithField)
                    throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as bytes and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the bytes.
    `parser` - Computes byte for string values.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.IndexReader, java.lang.String)` will also be computed and stored in the FieldCache.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getShorts

    short[] getShorts(IndexReader reader,
                      String field)
                      throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as shorts and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the shorts.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getShorts

    short[] getShorts(IndexReader reader,
                      String field,
                      FieldCache.ShortParser parser)
                      throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as shorts and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the shorts.
    `parser` - Computes short for string values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getShorts

    short[] getShorts(IndexReader reader,
                      String field,
                      FieldCache.ShortParser parser,
                      boolean setDocsWithField)
                      throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as shorts and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the shorts.
    `parser` - Computes short for string values.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.IndexReader, java.lang.String)` will also be computed and stored in the FieldCache.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getInts

    int[] getInts(IndexReader reader,
                  String field)
                  throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the integers.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getInts

    int[] getInts(IndexReader reader,
                  String field,
                  FieldCache.IntParser parser)
                  throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the integers.
    `parser` - Computes integer for string values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getInts

    int[] getInts(IndexReader reader,
                  String field,
                  FieldCache.IntParser parser,
                  boolean setDocsWithField)
                  throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the integers.
    `parser` - Computes integer for string values.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.IndexReader, java.lang.String)` will also be computed and stored in the FieldCache.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getFloats

    float[] getFloats(IndexReader reader,
                      String field)
                      throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as floats and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the floats.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getFloats

    float[] getFloats(IndexReader reader,
                      String field,
                      FieldCache.FloatParser parser)
                      throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as floats and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the floats.
    `parser` - Computes float for string values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getFloats

    float[] getFloats(IndexReader reader,
                      String field,
                      FieldCache.FloatParser parser,
                      boolean setDocsWithField)
                      throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as floats and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the floats.
    `parser` - Computes float for string values.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.IndexReader, java.lang.String)` will also be computed and stored in the FieldCache.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getLongs

    long[] getLongs(IndexReader reader,
                    String field)
                    throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as longs and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the longs.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getLongs

    long[] getLongs(IndexReader reader,
                    String field,
                    FieldCache.LongParser parser)
                    throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as longs and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the longs.
    `parser` - Computes integer for string values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getLongs

    long[] getLongs(IndexReader reader,
                    String field,
                    FieldCache.LongParser parser,
                    boolean setDocsWithField)
                    throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as longs and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the longs.
    `parser` - Computes integer for string values.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.IndexReader, java.lang.String)` will also be computed and stored in the FieldCache.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getDoubles

    double[] getDoubles(IndexReader reader,
                        String field)
                        throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as integers and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the doubles.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getDoubles

    double[] getDoubles(IndexReader reader,
                        String field,
                        FieldCache.DoubleParser parser)
                        throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as doubles and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the doubles.
    `parser` - Computes integer for string values.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getDoubles

    double[] getDoubles(IndexReader reader,
                        String field,
                        FieldCache.DoubleParser parser,
                        boolean setDocsWithField)
                        throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the terms in `field` as doubles and returns an array of size `reader.maxDoc()` of the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the doubles.
    `parser` - Computes integer for string values.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.IndexReader, java.lang.String)` will also be computed and stored in the FieldCache.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getStrings

    String[] getStrings(IndexReader reader,
                        String field)
                        throws IOException

  Checks the internal cache for an appropriate entry, and if none is found, reads the term values in `field` and returns an array of size `reader.maxDoc()` containing the value each document has in the given field.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the strings.
  Returns:
    The values in the given field for each document.
  Throws:
    `IOException` - If any error occurs.

### getStringIndex

    FieldCache.StringIndex getStringIndex(IndexReader reader,
                                          String field)
                                          throws IOException

  Checks the internal cache for an appropriate entry, and if none is found reads the term values in `field` and returns an array of them in natural order, along with an array telling which element in the term array each document uses.

  Parameters:
    `reader` - Used to get field values.
    `field` - Which field contains the strings.
  Returns:
    Array of terms and index into the array for each document.
  Throws:
    `IOException` - If any error occurs.

### getCacheEntries

    FieldCache.CacheEntry[] getCacheEntries()

  EXPERT: Generates an array of CacheEntry objects representing all items currently in the FieldCache.

  NOTE: These CacheEntry objects maintain a strong reference to the Cached Values. Maintaining references to a CacheEntry the IndexReader associated with it has garbage collected will prevent the Value itself from being garbage collected when the Cache drops the WeakReference.

  WARNING: This API is experimental and might change in incompatible ways in the next release.

### purgeAllCaches

    void purgeAllCaches()

  EXPERT: Instructs the FieldCache to forcibly expunge all entries from the underlying caches. This is intended only to be used for test methods as a way to ensure a known base state of the Cache (with out needing to rely on GC to free WeakReferences). It should not be relied on for "Cache maintenance" in general application code.

  WARNING: This API is experimental and might change in incompatible ways in the next release.

### purge

    void purge(IndexReader r)

  Expert: drops all cache entries associated with this reader. NOTE: this reader must precisely match the reader that the cache entry is keyed on. If you pass a top-level reader, it usually will have no effect as Lucene now caches at the segment reader level.

### setInfoStream

    void setInfoStream(PrintStream stream)

  If non-null, FieldCacheImpl will warn whenever entries are created that are not sane according to `FieldCacheSanityChecker`.

### getInfoStream

    PrintStream getInfoStream()

  counterpart of `setInfoStream(PrintStream)`