org.apache.lucene.index
Class DocValues

java.lang.Object
  extended by org.apache.lucene.index.DocValues
All Implemented Interfaces:
Closeable

public abstract class DocValues
extends Object
implements Closeable

DocValues provides a dense per-document typed storage for fast value access based on the lucene internal document id. DocValues exposes two distinct APIs:

DocValues are exposed via AtomicReader.docValues(String) on a per-segment basis. For best performance DocValues should be consumed per-segment just like IndexReader.

DocValues are fully integrated into the DocValuesFormat API.

NOTE: DocValues is a strongly typed per-field API. Type changes within an indexing session can result in exceptions if the type has changed in a way that the previously give type for a field can't promote the value without losing information. For instance a field initially indexed with DocValues.Type.FIXED_INTS_32 can promote a value with DocValues.Type.FIXED_INTS_8 but can't promote DocValues.Type.FIXED_INTS_64. During segment merging type-promotion exceptions are suppressed. Fields will be promoted to their common denominator or automatically transformed into a 3rd type like DocValues.Type.BYTES_VAR_STRAIGHT to prevent data loss and merge exceptions. This behavior is considered best-effort might change in future releases.

DocValues are exposed via the Field API with type safe specializations for each type variant:

See DocValues.Type for limitations of each type variant.

See Also:
DocValuesFormat.docsConsumer(org.apache.lucene.index.PerDocWriteState)
WARNING: This API is experimental and might change in incompatible ways in the next release.

Nested Class Summary
static class DocValues.SortedSource
          A sorted variant of DocValues.Source for byte[] values per document.
static class DocValues.Source
          Source of per document values like long, double or BytesRef depending on the DocValues fields DocValues.Type.
static class DocValues.SourceCache
          Abstract base class for DocValues DocValues.Source cache.
static class DocValues.Type
          Type specifies the DocValues type for a certain field.
 
Field Summary
static DocValues[] EMPTY_ARRAY
          Zero length DocValues array.
 
Constructor Summary
protected DocValues()
          Sole constructor.
 
Method Summary
 void close()
          Closes this DocValues instance.
static DocValues.SortedSource getDefaultSortedSource(DocValues.Type type, int size)
          Returns a SortedSource that always returns default (missing) values for all documents.
static DocValues.Source getDefaultSource(DocValues.Type type)
          Returns a Source that always returns default (missing) values for all documents.
 DocValues.Source getDirectSource()
          Returns a disk resident DocValues.Source instance through the current DocValues.SourceCache.
 DocValues.Source getSource()
          Returns a DocValues.Source instance through the current DocValues.SourceCache.
abstract  DocValues.Type getType()
          Returns the DocValues.Type of this DocValues instance
 int getValueSize()
          Returns the size per value in bytes or -1 iff size per value is variable.
protected abstract  DocValues.Source loadDirectSource()
          Loads a new direct source instance from this DocValues field instance.
protected abstract  DocValues.Source loadSource()
          Loads a new DocValues.Source instance for this DocValues field instance.
 void setCache(DocValues.SourceCache cache)
          Sets the DocValues.SourceCache used by this DocValues instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_ARRAY

public static final DocValues[] EMPTY_ARRAY
Zero length DocValues array.

Constructor Detail

DocValues

protected DocValues()
Sole constructor. (For invocation by subclass constructors, typically implicit.)

Method Detail

loadSource

protected abstract DocValues.Source loadSource()
                                        throws IOException
Loads a new DocValues.Source instance for this DocValues field instance. Source instances returned from this method are not cached. It is the callers responsibility to maintain the instance and release its resources once the source is not needed anymore.

For managed DocValues.Source instances see getSource().

Throws:
IOException
See Also:
getSource(), setCache(SourceCache)

getSource

public DocValues.Source getSource()
                           throws IOException
Returns a DocValues.Source instance through the current DocValues.SourceCache. Iff no DocValues.Source has been loaded into the cache so far the source will be loaded through loadSource() and passed to the DocValues.SourceCache. The caller of this method should not close the obtained DocValues.Source instance unless it is not needed for the rest of its life time.

DocValues.Source instances obtained from this method are closed / released from the cache once this DocValues instance is closed by the IndexReader, Fields or the DocValues was created from.

Throws:
IOException

getDirectSource

public DocValues.Source getDirectSource()
                                 throws IOException
Returns a disk resident DocValues.Source instance through the current DocValues.SourceCache. Direct Sources are cached per thread in the DocValues.SourceCache. The obtained instance should not be shared with other threads.

Throws:
IOException

loadDirectSource

protected abstract DocValues.Source loadDirectSource()
                                              throws IOException
Loads a new direct source instance from this DocValues field instance. Source instances returned from this method are not cached. It is the callers responsibility to maintain the instance and release its resources once the source is not needed anymore.

For managed direct source instances see getDirectSource().

Throws:
IOException
See Also:
getDirectSource(), setCache(SourceCache)

getType

public abstract DocValues.Type getType()
Returns the DocValues.Type of this DocValues instance


close

public void close()
           throws IOException
Closes this DocValues instance. This method should only be called by the creator of this DocValues instance. API users should not close DocValues instances.

Specified by:
close in interface Closeable
Throws:
IOException

getValueSize

public int getValueSize()
Returns the size per value in bytes or -1 iff size per value is variable.

Returns:
the size per value in bytes or -1 iff size per value is variable.

setCache

public void setCache(DocValues.SourceCache cache)
Sets the DocValues.SourceCache used by this DocValues instance. This method should be called before loadSource() is called. All DocValues.Source instances in the currently used cache will be closed before the new cache is installed.

Note: All instances previously obtained from loadSource() will be lost.

Throws:
IllegalArgumentException - if the given cache is null

getDefaultSource

public static DocValues.Source getDefaultSource(DocValues.Type type)
Returns a Source that always returns default (missing) values for all documents.


getDefaultSortedSource

public static DocValues.SortedSource getDefaultSortedSource(DocValues.Type type,
                                                            int size)
Returns a SortedSource that always returns default (missing) values for all documents.



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