org.apache.lucene.search

## Interface FieldCache

- All Known Subinterfaces:
    ExtendedFieldCache

      public interface FieldCache

  Expert: Maintains caches of term values.

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

  Since:
    lucene 1.4
  Version:
    $Id: FieldCache.java 950451 2010-06-02 09:33:57Z mikemccand $
  See Also:
    `FieldCacheSanityChecker`

- - ### 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.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

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

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Object` | `getAuto(IndexReader reader, java.lang.String field)` Deprecated. Please specify the exact type, instead. Especially, guessing does not work with the new `NumericField` type.
    `byte[]` | `getBytes(IndexReader reader, java.lang.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, java.lang.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.
    `FieldCache.CacheEntry[]` | `getCacheEntries()` EXPERT: Generates an array of CacheEntry objects representing all items currently in the FieldCache.
    `java.lang.Comparable[]` | `getCustom(IndexReader reader, java.lang.String field, SortComparator comparator)` Deprecated. Please implement `FieldComparatorSource` directly, instead.
    `double[]` | `getDoubles(IndexReader reader, java.lang.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, java.lang.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.
    `float[]` | `getFloats(IndexReader reader, java.lang.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, java.lang.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.
    `java.io.PrintStream` | `getInfoStream()` counterpart of `setInfoStream(PrintStream)`
    `int[]` | `getInts(IndexReader reader, java.lang.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, java.lang.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.
    `long[]` | `getLongs(IndexReader reader, java.lang.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, java.lang.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.
    `short[]` | `getShorts(IndexReader reader, java.lang.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, java.lang.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.
    `FieldCache.StringIndex` | `getStringIndex(IndexReader reader, java.lang.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.
    `java.lang.String[]` | `getStrings(IndexReader reader, java.lang.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(java.io.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

    - #### getBytes

          byte[] getBytes(IndexReader reader,
                          java.lang.String field)
                   throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getBytes

          byte[] getBytes(IndexReader reader,
                          java.lang.String field,
                          FieldCache.ByteParser parser)
                   throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getShorts

          short[] getShorts(IndexReader reader,
                            java.lang.String field)
                     throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getShorts

          short[] getShorts(IndexReader reader,
                            java.lang.String field,
                            FieldCache.ShortParser parser)
                     throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getInts

          int[] getInts(IndexReader reader,
                        java.lang.String field)
                 throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getInts

          int[] getInts(IndexReader reader,
                        java.lang.String field,
                        FieldCache.IntParser parser)
                 throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getFloats

          float[] getFloats(IndexReader reader,
                            java.lang.String field)
                     throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getFloats

          float[] getFloats(IndexReader reader,
                            java.lang.String field,
                            FieldCache.FloatParser parser)
                     throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getLongs

          long[] getLongs(IndexReader reader,
                          java.lang.String field)
                   throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getLongs

          long[] getLongs(IndexReader reader,
                          java.lang.String field,
                          FieldCache.LongParser parser)
                   throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getDoubles

          double[] getDoubles(IndexReader reader,
                              java.lang.String field)
                       throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getDoubles

          double[] getDoubles(IndexReader reader,
                              java.lang.String field,
                              FieldCache.DoubleParser parser)
                       throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getStrings

          java.lang.String[] getStrings(IndexReader reader,
                                        java.lang.String field)
                                 throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getStringIndex

          FieldCache.StringIndex getStringIndex(IndexReader reader,
                                                java.lang.String field)
                                         throws java.io.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:
        `java.io.IOException` - If any error occurs.

    - #### getAuto

          java.lang.Object getAuto(IndexReader reader,
                                   java.lang.String field)
                            throws java.io.IOException

      Deprecated. Please specify the exact type, instead. Especially, guessing does not work with the new `NumericField` type.
      Checks the internal cache for an appropriate entry, and if none is found reads `field` to see if it contains integers, longs, floats or strings, and then calls one of the other methods in this class to get the values. For string values, a StringIndex is returned. After calling this method, there is an entry in the cache for both type `AUTO` and the actual found type.
      Parameters:
        `reader` - Used to get field values.
        `field` - Which field contains the values.
      Returns:
        int[], long[], float[] or StringIndex.
      Throws:
        `java.io.IOException` - If any error occurs.

    - #### getCustom

          java.lang.Comparable[] getCustom(IndexReader reader,
                                           java.lang.String field,
                                           SortComparator comparator)
                                    throws java.io.IOException

      Deprecated. Please implement `FieldComparatorSource` directly, instead.
      Checks the internal cache for an appropriate entry, and if none is found reads the terms out of `field` and calls the given SortComparator to get the sort values. A hit in the cache will happen if `reader`, `field`, and `comparator` are the same (using `equals()`) as a previous call to this method.
      Parameters:
        `reader` - Used to get field values.
        `field` - Which field contains the values.
        `comparator` - Used to convert terms into something to sort by.
      Returns:
        Array of sort objects, one for each document.
      Throws:
        `java.io.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 WeakRefrence.

      EXPERIMENTAL API: This API is considered extremely advanced and experimental. It may be removed or altered w/o warning in future releases of Lucene.

    - #### 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.

      EXPERIMENTAL API: This API is considered extremely advanced and experimental. It may be removed or altered w/o warning in future releases of Lucene.

    - #### 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(java.io.PrintStream stream)

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

    - #### getInfoStream

          java.io.PrintStream getInfoStream()

      counterpart of `setInfoStream(PrintStream)`

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