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

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

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