## 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`
NOTE: This API is for internal purposes only and might change in incompatible ways in the next release.

Nested Class Summary
`static interface` `FieldCache.ByteParser` Interface to parse bytes from document fields.
`static class` `FieldCache.Bytes` Field values as 8-bit signed bytes
`static class` `FieldCache.CacheEntry` EXPERT: A unique Identifier/Description for each item in the FieldCache.
`static class` `FieldCache.CreationPlaceholder` Placeholder indicating creation of this cache is currently in-progress.
`static interface` `FieldCache.DoubleParser` Interface to parse doubles from document fields.
`static class` `FieldCache.Doubles` Field values as 64-bit doubles
`static interface` `FieldCache.FloatParser` Interface to parse floats from document fields.
`static class` `FieldCache.Floats` Field values as 32-bit floats
`static interface` `FieldCache.IntParser` Interface to parse ints from document fields.
`static class` `FieldCache.Ints` Field values as 32-bit signed integers
`static interface` `FieldCache.LongParser` Interface to parse long from document fields.
`static class` `FieldCache.Longs` Field values as 64-bit signed long integers
`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.Shorts` Field values as 16-bit signed shorts

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 SortedDocValues` `EMPTY_TERMSINDEX` Returns MISSING/-1 ordinal for every document
`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`, e.g.
`static FieldCache.LongParser` `NUMERIC_UTILS_LONG_PARSER` A parser instance for long values encoded by `NumericUtils`, e.g.

Method Summary
`FieldCache.Bytes` `getBytes(AtomicReader reader, String field, boolean setDocsWithField)` 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.
`FieldCache.Bytes` `getBytes(AtomicReader 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(AtomicReader 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.
`SortedSetDocValues` `getDocTermOrds(AtomicReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the term values in `field` and returns a `DocTermOrds` instance, providing a method to retrieve the terms (as ords) per document.
`FieldCache.Doubles` `getDoubles(AtomicReader reader, String field, 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.
`FieldCache.Doubles` `getDoubles(AtomicReader 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.
`FieldCache.Floats` `getFloats(AtomicReader reader, String field, 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.
`FieldCache.Floats` `getFloats(AtomicReader 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)`
`FieldCache.Ints` `getInts(AtomicReader reader, String field, 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.
`FieldCache.Ints` `getInts(AtomicReader 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.
`FieldCache.Longs` `getLongs(AtomicReader reader, String field, 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.
`FieldCache.Longs` `getLongs(AtomicReader 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.
`FieldCache.Shorts` `getShorts(AtomicReader reader, String field, 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.Shorts` `getShorts(AtomicReader 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.
`BinaryDocValues` `getTerms(AtomicReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the term values in `field` and returns a `BinaryDocValues` instance, providing a method to retrieve the term (as a BytesRef) per document.
`BinaryDocValues` `getTerms(AtomicReader reader, String field, float acceptableOverheadRatio)` Expert: just like `getTerms(AtomicReader,String)`, but you can specify whether more RAM should be consumed in exchange for faster lookups (default is "true").
`SortedDocValues` `getTermsIndex(AtomicReader reader, String field)` Checks the internal cache for an appropriate entry, and if none is found, reads the term values in `field` and returns a `SortedDocValues` instance, providing methods to retrieve sort ordinals and terms (as a ByteRef) per document.
`SortedDocValues` `getTermsIndex(AtomicReader reader, String field, float acceptableOverheadRatio)` Expert: just like `getTermsIndex(AtomicReader,String)`, but you can specify whether more RAM should be consumed in exchange for faster lookups (default is "true").
`void` `purge(AtomicReader 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

### EMPTY_TERMSINDEX

    static final SortedDocValues EMPTY_TERMSINDEX

  Returns MISSING/-1 ordinal for every document

### 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`, e.g. when indexed via `IntField`/`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 `FloatField`/`NumericTokenStream`.

### NUMERIC_UTILS_LONG_PARSER

    static final FieldCache.LongParser NUMERIC_UTILS_LONG_PARSER

  A parser instance for long values encoded by `NumericUtils`, e.g. when indexed via `LongField`/`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 `DoubleField`/`NumericTokenStream`.

Method Detail

### getDocsWithField

    Bits getDocsWithField(AtomicReader 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. Note that if the field was only indexed as DocValues then this method will not work (it will return a Bits stating that no documents contain the field).

  Throws:
    `IOException`

### getBytes

    FieldCache.Bytes getBytes(AtomicReader reader,
                              String field,
                              boolean setDocsWithField)
                              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.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.AtomicReader, 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.

### getBytes

    FieldCache.Bytes getBytes(AtomicReader 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.AtomicReader, 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

    FieldCache.Shorts getShorts(AtomicReader reader,
                                String field,
                                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.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.AtomicReader, 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

    FieldCache.Shorts getShorts(AtomicReader 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.AtomicReader, 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

    FieldCache.Ints getInts(AtomicReader reader,
                            String field,
                            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.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.AtomicReader, 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

    FieldCache.Ints getInts(AtomicReader 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.AtomicReader, 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

    FieldCache.Floats getFloats(AtomicReader reader,
                                String field,
                                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.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.AtomicReader, 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

    FieldCache.Floats getFloats(AtomicReader 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.AtomicReader, 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

    FieldCache.Longs getLongs(AtomicReader reader,
                              String field,
                              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.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.AtomicReader, 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

    FieldCache.Longs getLongs(AtomicReader 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.AtomicReader, 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

    FieldCache.Doubles getDoubles(AtomicReader reader,
                                  String field,
                                  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 doubles.
    `setDocsWithField` - If true then `getDocsWithField(org.apache.lucene.index.AtomicReader, 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

    FieldCache.Doubles getDoubles(AtomicReader 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.AtomicReader, 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.

### getTerms

    BinaryDocValues getTerms(AtomicReader 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 a `BinaryDocValues` instance, providing a method to retrieve the term (as a BytesRef) per document.

  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.

### getTerms

    BinaryDocValues getTerms(AtomicReader reader,
                             String field,
                             float acceptableOverheadRatio)
                             throws IOException

  Expert: just like `getTerms(AtomicReader,String)`, but you can specify whether more RAM should be consumed in exchange for faster lookups (default is "true"). Note that the first call for a given reader and field "wins", subsequent calls will share the same cache entry.

  Throws:
    `IOException`

### getTermsIndex

    SortedDocValues getTermsIndex(AtomicReader 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 a `SortedDocValues` instance, providing methods to retrieve sort ordinals and terms (as a ByteRef) per document.

  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.

### getTermsIndex

    SortedDocValues getTermsIndex(AtomicReader reader,
                                  String field,
                                  float acceptableOverheadRatio)
                                  throws IOException

  Expert: just like `getTermsIndex(AtomicReader,String)`, but you can specify whether more RAM should be consumed in exchange for faster lookups (default is "true"). Note that the first call for a given reader and field "wins", subsequent calls will share the same cache entry.

  Throws:
    `IOException`

### getDocTermOrds

    SortedSetDocValues getDocTermOrds(AtomicReader 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 a `DocTermOrds` instance, providing a method to retrieve the terms (as ords) per document.

  Parameters:
    `reader` - Used to build a `DocTermOrds` instance
    `field` - Which field contains the strings.
  Returns:
    a `DocTermOrds` instance
  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 AtomicIndexReader 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(AtomicReader 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)`

Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.