FieldCache (Lucene 4.2.0 API)

```
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

Nested Classes
Modifier and Type	Interface and Description
`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

Fields
Modifier and Type	Field and Description
`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

Methods
Modifier and Type	Method and Description
`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)

Interface FieldCache

Nested Class Summary

Field Summary

Method Summary

Field Detail

EMPTY_TERMSINDEX

DEFAULT

DEFAULT_BYTE_PARSER

DEFAULT_SHORT_PARSER

DEFAULT_INT_PARSER

DEFAULT_FLOAT_PARSER

DEFAULT_LONG_PARSER

DEFAULT_DOUBLE_PARSER

NUMERIC_UTILS_INT_PARSER

NUMERIC_UTILS_FLOAT_PARSER

NUMERIC_UTILS_LONG_PARSER

NUMERIC_UTILS_DOUBLE_PARSER

Method Detail

getDocsWithField

getBytes

getBytes

getShorts

getShorts

getInts

getInts

getFloats

getFloats

getLongs

getLongs

getDoubles

getDoubles

getTerms

getTerms

getTermsIndex

getTermsIndex

getDocTermOrds

getCacheEntries

purgeAllCaches

purge

setInfoStream

getInfoStream