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
          Deprecated. 
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
          Deprecated. 
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
          Deprecated. 
static FieldCache.DoubleParser DEFAULT_DOUBLE_PARSER
          Deprecated. 
static FieldCache.FloatParser DEFAULT_FLOAT_PARSER
          Deprecated. 
static FieldCache.IntParser DEFAULT_INT_PARSER
          Deprecated. 
static FieldCache.LongParser DEFAULT_LONG_PARSER
          Deprecated. 
static FieldCache.ShortParser DEFAULT_SHORT_PARSER
          Deprecated. 
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)
          Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.
 FieldCache.Bytes getBytes(AtomicReader reader, String field, FieldCache.ByteParser parser, boolean setDocsWithField)
          Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.
 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)
          Returns a FieldCache.Doubles over the values found in documents in the given field.
 FieldCache.Doubles getDoubles(AtomicReader reader, String field, FieldCache.DoubleParser parser, boolean setDocsWithField)
          Returns a FieldCache.Doubles over the values found in documents in the given field.
 FieldCache.Floats getFloats(AtomicReader reader, String field, boolean setDocsWithField)
          Returns a FieldCache.Floats over the values found in documents in the given field.
 FieldCache.Floats getFloats(AtomicReader reader, String field, FieldCache.FloatParser parser, boolean setDocsWithField)
          Returns a FieldCache.Floats over the values found in documents in the given field.
 PrintStream getInfoStream()
          counterpart of setInfoStream(PrintStream)
 FieldCache.Ints getInts(AtomicReader reader, String field, boolean setDocsWithField)
          Returns an FieldCache.Ints over the values found in documents in the given field.
 FieldCache.Ints getInts(AtomicReader reader, String field, FieldCache.IntParser parser, boolean setDocsWithField)
          Returns an FieldCache.Ints over the values found in documents in the given field.
 FieldCache.Longs getLongs(AtomicReader reader, String field, boolean setDocsWithField)
          Returns a FieldCache.Longs over the values found in documents in the given field.
 FieldCache.Longs getLongs(AtomicReader reader, String field, FieldCache.LongParser parser, boolean setDocsWithField)
          Returns a FieldCache.Longs over the values found in documents in the given field.
 FieldCache.Shorts getShorts(AtomicReader reader, String field, boolean setDocsWithField)
          Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.
 FieldCache.Shorts getShorts(AtomicReader reader, String field, FieldCache.ShortParser parser, boolean setDocsWithField)
          Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.
 BinaryDocValues getTerms(AtomicReader reader, String field, boolean setDocsWithField)
          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, boolean setDocsWithField, float acceptableOverheadRatio)
          Expert: just like getTerms(AtomicReader,String,boolean), 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 purgeAllCaches()
           EXPERT: Instructs the FieldCache to forcibly expunge all entries from the underlying caches.
 void purgeByCacheKey(Object coreCacheKey)
          Expert: drops all cache entries associated with this reader IndexReader.getCoreCacheKey().
 void setInfoStream(PrintStream stream)
          If non-null, FieldCacheImpl will warn whenever entries are created that are not sane according to FieldCacheSanityChecker.
 

Field Detail

DEFAULT

static final FieldCache DEFAULT
Expert: The cache used internally by sorting and range query classes.


DEFAULT_BYTE_PARSER

@Deprecated
static final FieldCache.ByteParser DEFAULT_BYTE_PARSER
Deprecated. 
The default parser for byte values, which are encoded by Byte.toString(byte)


DEFAULT_SHORT_PARSER

@Deprecated
static final FieldCache.ShortParser DEFAULT_SHORT_PARSER
Deprecated. 
The default parser for short values, which are encoded by Short.toString(short)


DEFAULT_INT_PARSER

@Deprecated
static final FieldCache.IntParser DEFAULT_INT_PARSER
Deprecated. 
The default parser for int values, which are encoded by Integer.toString(int)


DEFAULT_FLOAT_PARSER

@Deprecated
static final FieldCache.FloatParser DEFAULT_FLOAT_PARSER
Deprecated. 
The default parser for float values, which are encoded by Float.toString(float)


DEFAULT_LONG_PARSER

@Deprecated
static final FieldCache.LongParser DEFAULT_LONG_PARSER
Deprecated. 
The default parser for long values, which are encoded by Long.toString(long)


DEFAULT_DOUBLE_PARSER

@Deprecated
static final FieldCache.DoubleParser DEFAULT_DOUBLE_PARSER
Deprecated. 
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.

Throws:
IOException

getBytes

@Deprecated
FieldCache.Bytes getBytes(AtomicReader reader,
                                     String field,
                                     boolean setDocsWithField)
                          throws IOException
Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.

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

@Deprecated
FieldCache.Bytes getBytes(AtomicReader reader,
                                     String field,
                                     FieldCache.ByteParser parser,
                                     boolean setDocsWithField)
                          throws IOException
Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.

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

@Deprecated
FieldCache.Shorts getShorts(AtomicReader reader,
                                       String field,
                                       boolean setDocsWithField)
                            throws IOException
Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.

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

@Deprecated
FieldCache.Shorts getShorts(AtomicReader reader,
                                       String field,
                                       FieldCache.ShortParser parser,
                                       boolean setDocsWithField)
                            throws IOException
Deprecated. (4.4) Index as a numeric field using IntField and then use getInts(AtomicReader, String, boolean) instead.

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
Returns an FieldCache.Ints over the values found in documents in the given field.

Throws:
IOException
See Also:
getInts(AtomicReader, String, IntParser, boolean)

getInts

FieldCache.Ints getInts(AtomicReader reader,
                        String field,
                        FieldCache.IntParser parser,
                        boolean setDocsWithField)
                        throws IOException
Returns an FieldCache.Ints over the values found in documents in the given field. If the field was indexed as NumericDocValuesField, it simply uses AtomicReader.getNumericDocValues(String) to read the values. Otherwise, it checks the internal cache for an appropriate entry, and if none is found, reads the terms in field as ints 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 int for string values. May be null if the requested field was indexed as NumericDocValuesField or IntField.
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
Returns a FieldCache.Floats over the values found in documents in the given field.

Throws:
IOException
See Also:
getFloats(AtomicReader, String, FloatParser, boolean)

getFloats

FieldCache.Floats getFloats(AtomicReader reader,
                            String field,
                            FieldCache.FloatParser parser,
                            boolean setDocsWithField)
                            throws IOException
Returns a FieldCache.Floats over the values found in documents in the given field. If the field was indexed as NumericDocValuesField, it simply uses AtomicReader.getNumericDocValues(String) to read the values. Otherwise, it 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. May be null if the requested field was indexed as NumericDocValuesField or FloatField.
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
Returns a FieldCache.Longs over the values found in documents in the given field.

Throws:
IOException
See Also:
getLongs(AtomicReader, String, LongParser, boolean)

getLongs

FieldCache.Longs getLongs(AtomicReader reader,
                          String field,
                          FieldCache.LongParser parser,
                          boolean setDocsWithField)
                          throws IOException
Returns a FieldCache.Longs over the values found in documents in the given field. If the field was indexed as NumericDocValuesField, it simply uses AtomicReader.getNumericDocValues(String) to read the values. Otherwise, it 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 long for string values. May be null if the requested field was indexed as NumericDocValuesField or LongField.
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
Returns a FieldCache.Doubles over the values found in documents in the given field.

Throws:
IOException
See Also:
getDoubles(AtomicReader, String, DoubleParser, boolean)

getDoubles

FieldCache.Doubles getDoubles(AtomicReader reader,
                              String field,
                              FieldCache.DoubleParser parser,
                              boolean setDocsWithField)
                              throws IOException
Returns a FieldCache.Doubles over the values found in documents in the given field. If the field was indexed as NumericDocValuesField, it simply uses AtomicReader.getNumericDocValues(String) to read the values. Otherwise, it 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 longs.
parser - Computes double for string values. May be null if the requested field was indexed as NumericDocValuesField or DoubleField.
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,
                         boolean setDocsWithField)
                         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.
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,
                         boolean setDocsWithField,
                         float acceptableOverheadRatio)
                         throws IOException
Expert: just like getTerms(AtomicReader,String,boolean), 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.

purgeByCacheKey

void purgeByCacheKey(Object coreCacheKey)
Expert: drops all cache entries associated with this reader IndexReader.getCoreCacheKey(). NOTE: this cache key 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-2014 Apache Software Foundation. All Rights Reserved.