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

Nested Class Summary

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

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

byte[]	getBytes(IndexReader reader, 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, 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.
byte[]	getBytes(IndexReader 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(IndexReader 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.
double[]	getDoubles(IndexReader reader, 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, 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.
double[]	getDoubles(IndexReader 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.
float[]	getFloats(IndexReader reader, 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, 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.
float[]	getFloats(IndexReader 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)
int[]	getInts(IndexReader reader, 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, 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.
int[]	getInts(IndexReader 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.
long[]	getLongs(IndexReader reader, 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, 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.
long[]	getLongs(IndexReader 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.
short[]	getShorts(IndexReader reader, 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, 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.
short[]	getShorts(IndexReader 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.
FieldCache.StringIndex	getStringIndex(IndexReader reader, 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.
String[]	getStrings(IndexReader reader, 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(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

getDocsWithField

Bits getDocsWithField(IndexReader 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

byte[] getBytes(IndexReader reader,
                String field)
                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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getBytes

byte[] getBytes(IndexReader reader,
                String field,
                FieldCache.ByteParser parser)
                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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getBytes

byte[] getBytes(IndexReader 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.IndexReader, 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

short[] getShorts(IndexReader reader,
                  String field)
                  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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getShorts

short[] getShorts(IndexReader reader,
                  String field,
                  FieldCache.ShortParser parser)
                  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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getShorts

short[] getShorts(IndexReader 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.IndexReader, 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

int[] getInts(IndexReader reader,
              String field)
              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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getInts

int[] getInts(IndexReader reader,
              String field,
              FieldCache.IntParser parser)
              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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getInts

int[] getInts(IndexReader 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.IndexReader, 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

float[] getFloats(IndexReader reader,
                  String field)
                  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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getFloats

float[] getFloats(IndexReader reader,
                  String field,
                  FieldCache.FloatParser parser)
                  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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getFloats

float[] getFloats(IndexReader 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.IndexReader, 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

long[] getLongs(IndexReader reader,
                String field)
                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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getLongs

long[] getLongs(IndexReader reader,
                String field,
                FieldCache.LongParser parser)
                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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getLongs

long[] getLongs(IndexReader 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.IndexReader, 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

double[] getDoubles(IndexReader reader,
                    String field)
                    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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getDoubles

double[] getDoubles(IndexReader reader,
                    String field,
                    FieldCache.DoubleParser parser)
                    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.

Returns:

The values in the given field for each document.

Throws:

IOException - If any error occurs.

getDoubles

double[] getDoubles(IndexReader 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.IndexReader, 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.

getStrings

String[] getStrings(IndexReader 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 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:

IOException - If any error occurs.

getStringIndex

FieldCache.StringIndex getStringIndex(IndexReader 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 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:

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