org.apache.lucene.index
Class DirectoryReader

java.lang.Object
  extended by org.apache.lucene.index.IndexReader
      extended by org.apache.lucene.index.CompositeReader
          extended by org.apache.lucene.index.BaseCompositeReader<AtomicReader>
              extended by org.apache.lucene.index.DirectoryReader
All Implemented Interfaces:
Closeable

public abstract class DirectoryReader
extends BaseCompositeReader<AtomicReader>

DirectoryReader is an implementation of CompositeReader that can read indexes in a Directory.

DirectoryReader instances are usually constructed with a call to one of the static open() methods, e.g. open(Directory).

For efficiency, in this API documents are often referred to via document numbers, non-negative integers which each name a unique document in the index. These document numbers are ephemeral -- they may change as documents are added to and deleted from an index. Clients should thus not rely on a given document having the same number between sessions.

NOTE: IndexReader instances are completely thread safe, meaning multiple threads can call any of its methods, concurrently. If your application requires external synchronization, you should not synchronize on the IndexReader instance; use your own (non-Lucene) objects instead.


Nested Class Summary
 
Nested classes/interfaces inherited from class org.apache.lucene.index.IndexReader
IndexReader.ReaderClosedListener
 
Field Summary
static int DEFAULT_TERMS_INDEX_DIVISOR
          Default termInfosIndexDivisor.
protected  Directory directory
          The index directory.
 
Constructor Summary
protected DirectoryReader(Directory directory, AtomicReader[] segmentReaders)
          Expert: Constructs a DirectoryReader on the given subReaders.
 
Method Summary
 Directory directory()
          Returns the directory this index resides in.
protected abstract  DirectoryReader doOpenIfChanged()
          Implement this method to support openIfChanged(DirectoryReader).
protected abstract  DirectoryReader doOpenIfChanged(IndexCommit commit)
          Implement this method to support openIfChanged(DirectoryReader,IndexCommit).
protected abstract  DirectoryReader doOpenIfChanged(IndexWriter writer, boolean applyAllDeletes)
          Implement this method to support openIfChanged(DirectoryReader,IndexWriter,boolean).
abstract  IndexCommit getIndexCommit()
          Expert: return the IndexCommit that this reader has opened.
abstract  long getVersion()
          Version number when this IndexReader was opened.
static boolean indexExists(Directory directory)
          Returns true if an index exists at the specified directory.
abstract  boolean isCurrent()
          Check whether any new changes have occurred to the index since this reader was opened.
static List<IndexCommit> listCommits(Directory dir)
          Returns all commit points that exist in the Directory.
static DirectoryReader open(Directory directory)
          Returns a IndexReader reading the index in the given Directory
static DirectoryReader open(Directory directory, int termInfosIndexDivisor)
          Expert: Returns a IndexReader reading the index in the given Directory with the given termInfosIndexDivisor.
static DirectoryReader open(IndexCommit commit)
          Expert: returns an IndexReader reading the index in the given IndexCommit.
static DirectoryReader open(IndexCommit commit, int termInfosIndexDivisor)
          Expert: returns an IndexReader reading the index in the given IndexCommit and termInfosIndexDivisor.
static DirectoryReader open(IndexWriter writer, boolean applyAllDeletes)
          Open a near real time IndexReader from the IndexWriter.
static DirectoryReader openIfChanged(DirectoryReader oldReader)
          If the index has changed since the provided reader was opened, open and return a new reader; else, return null.
static DirectoryReader openIfChanged(DirectoryReader oldReader, IndexCommit commit)
          If the IndexCommit differs from what the provided reader is searching, open and return a new reader; else, return null.
static DirectoryReader openIfChanged(DirectoryReader oldReader, IndexWriter writer, boolean applyAllDeletes)
          Expert: If there changes (committed or not) in the IndexWriter versus what the provided reader is searching, then open and return a new IndexReader searching both committed and uncommitted changes from the writer; else, return null (though, the current implementation never returns null).
 
Methods inherited from class org.apache.lucene.index.BaseCompositeReader
docFreq, document, getSequentialSubReaders, getTermVectors, hasDeletions, maxDoc, numDocs, readerBase, readerIndex, totalTermFreq
 
Methods inherited from class org.apache.lucene.index.CompositeReader
getContext, toString
 
Methods inherited from class org.apache.lucene.index.IndexReader
addReaderClosedListener, close, decRef, doClose, document, document, ensureOpen, equals, getCombinedCoreAndDeletesKey, getCoreCacheKey, getRefCount, getTermVector, hashCode, incRef, leaves, numDeletedDocs, registerParentReader, removeReaderClosedListener, tryIncRef
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_TERMS_INDEX_DIVISOR

public static final int DEFAULT_TERMS_INDEX_DIVISOR
Default termInfosIndexDivisor.

See Also:
Constant Field Values

directory

protected final Directory directory
The index directory.

Constructor Detail

DirectoryReader

protected DirectoryReader(Directory directory,
                          AtomicReader[] segmentReaders)
Expert: Constructs a DirectoryReader on the given subReaders.

Parameters:
segmentReaders - the wrapped atomic index segment readers. This array is returned by BaseCompositeReader.getSequentialSubReaders() and used to resolve the correct subreader for docID-based methods. Please note: This array is not cloned and not protected for modification outside of this reader. Subclasses of DirectoryReader should take care to not allow modification of this internal array, e.g. doOpenIfChanged().
Method Detail

open

public static DirectoryReader open(Directory directory)
                            throws IOException
Returns a IndexReader reading the index in the given Directory

Parameters:
directory - the index directory
Throws:
IOException - if there is a low-level IO error

open

public static DirectoryReader open(Directory directory,
                                   int termInfosIndexDivisor)
                            throws IOException
Expert: Returns a IndexReader reading the index in the given Directory with the given termInfosIndexDivisor.

Parameters:
directory - the index directory
termInfosIndexDivisor - Subsamples which indexed terms are loaded into RAM. This has the same effect as IndexWriterConfig.setTermIndexInterval(int) except that setting must be done at indexing time while this setting can be set per reader. When set to N, then one in every N*termIndexInterval terms in the index is loaded into memory. By setting this to a value > 1 you can reduce memory usage, at the expense of higher latency when loading a TermInfo. The default value is 1. Set this to -1 to skip loading the terms index entirely. NOTE: divisor settings > 1 do not apply to all PostingsFormat implementations, including the default one in this release. It only makes sense for terms indexes that can efficiently re-sample terms at load time.
Throws:
IOException - if there is a low-level IO error

open

public static DirectoryReader open(IndexWriter writer,
                                   boolean applyAllDeletes)
                            throws IOException
Open a near real time IndexReader from the IndexWriter.

Parameters:
writer - The IndexWriter to open from
applyAllDeletes - If true, all buffered deletes will be applied (made visible) in the returned reader. If false, the deletes are not applied but remain buffered (in IndexWriter) so that they will be applied in the future. Applying deletes can be costly, so if your app can tolerate deleted documents being returned you might gain some performance by passing false.
Returns:
The new IndexReader
Throws:
CorruptIndexException - if the index is corrupt
IOException - if there is a low-level IO error
See Also:
openIfChanged(DirectoryReader,IndexWriter,boolean)
WARNING: This API is experimental and might change in incompatible ways in the next release.

open

public static DirectoryReader open(IndexCommit commit)
                            throws IOException
Expert: returns an IndexReader reading the index in the given IndexCommit.

Parameters:
commit - the commit point to open
Throws:
IOException - if there is a low-level IO error

open

public static DirectoryReader open(IndexCommit commit,
                                   int termInfosIndexDivisor)
                            throws IOException
Expert: returns an IndexReader reading the index in the given IndexCommit and termInfosIndexDivisor.

Parameters:
commit - the commit point to open
termInfosIndexDivisor - Subsamples which indexed terms are loaded into RAM. This has the same effect as IndexWriterConfig.setTermIndexInterval(int) except that setting must be done at indexing time while this setting can be set per reader. When set to N, then one in every N*termIndexInterval terms in the index is loaded into memory. By setting this to a value > 1 you can reduce memory usage, at the expense of higher latency when loading a TermInfo. The default value is 1. Set this to -1 to skip loading the terms index entirely. NOTE: divisor settings > 1 do not apply to all PostingsFormat implementations, including the default one in this release. It only makes sense for terms indexes that can efficiently re-sample terms at load time.
Throws:
IOException - if there is a low-level IO error

openIfChanged

public static DirectoryReader openIfChanged(DirectoryReader oldReader)
                                     throws IOException
If the index has changed since the provided reader was opened, open and return a new reader; else, return null. The new reader, if not null, will be the same type of reader as the previous one, ie an NRT reader will open a new NRT reader, a MultiReader will open a new MultiReader, etc.

This method is typically far less costly than opening a fully new DirectoryReader as it shares resources (for example sub-readers) with the provided DirectoryReader, when possible.

The provided reader is not closed (you are responsible for doing so); if a new reader is returned you also must eventually close it. Be sure to never close a reader while other threads are still using it; see SearcherManager to simplify managing this.

Returns:
null if there are no changes; else, a new DirectoryReader instance which you must eventually close
Throws:
CorruptIndexException - if the index is corrupt
IOException - if there is a low-level IO error

openIfChanged

public static DirectoryReader openIfChanged(DirectoryReader oldReader,
                                            IndexCommit commit)
                                     throws IOException
If the IndexCommit differs from what the provided reader is searching, open and return a new reader; else, return null.

Throws:
IOException
See Also:
openIfChanged(DirectoryReader)

openIfChanged

public static DirectoryReader openIfChanged(DirectoryReader oldReader,
                                            IndexWriter writer,
                                            boolean applyAllDeletes)
                                     throws IOException
Expert: If there changes (committed or not) in the IndexWriter versus what the provided reader is searching, then open and return a new IndexReader searching both committed and uncommitted changes from the writer; else, return null (though, the current implementation never returns null).

This provides "near real-time" searching, in that changes made during an IndexWriter session can be quickly made available for searching without closing the writer nor calling IndexWriter.commit().

It's near real-time because there is no hard guarantee on how quickly you can get a new reader after making changes with IndexWriter. You'll have to experiment in your situation to determine if it's fast enough. As this is a new and experimental feature, please report back on your findings so we can learn, improve and iterate.

The very first time this method is called, this writer instance will make every effort to pool the readers that it opens for doing merges, applying deletes, etc. This means additional resources (RAM, file descriptors, CPU time) will be consumed.

For lower latency on reopening a reader, you should call IndexWriterConfig.setMergedSegmentWarmer(org.apache.lucene.index.IndexWriter.IndexReaderWarmer) to pre-warm a newly merged segment before it's committed to the index. This is important for minimizing index-to-search delay after a large merge.

If an addIndexes* call is running in another thread, then this reader will only search those segments from the foreign index that have been successfully copied over, so far.

NOTE: Once the writer is closed, any outstanding readers may continue to be used. However, if you attempt to reopen any of those readers, you'll hit an AlreadyClosedException.

Parameters:
writer - The IndexWriter to open from
applyAllDeletes - If true, all buffered deletes will be applied (made visible) in the returned reader. If false, the deletes are not applied but remain buffered (in IndexWriter) so that they will be applied in the future. Applying deletes can be costly, so if your app can tolerate deleted documents being returned you might gain some performance by passing false.
Returns:
DirectoryReader that covers entire index plus all changes made so far by this IndexWriter instance, or null if there are no new changes
Throws:
IOException - if there is a low-level IO error
WARNING: This API is experimental and might change in incompatible ways in the next release.

listCommits

public static List<IndexCommit> listCommits(Directory dir)
                                     throws IOException
Returns all commit points that exist in the Directory. Normally, because the default is KeepOnlyLastCommitDeletionPolicy, there would be only one commit point. But if you're using a custom IndexDeletionPolicy then there could be many commits. Once you have a given commit, you can open a reader on it by calling open(IndexCommit) There must be at least one commit in the Directory, else this method throws IndexNotFoundException. Note that if a commit is in progress while this method is running, that commit may or may not be returned.

Returns:
a sorted list of IndexCommits, from oldest to latest.
Throws:
IOException

indexExists

public static boolean indexExists(Directory directory)
Returns true if an index exists at the specified directory.

Parameters:
directory - the directory to check for an index
Returns:
true if an index exists; false otherwise

directory

public final Directory directory()
Returns the directory this index resides in.


doOpenIfChanged

protected abstract DirectoryReader doOpenIfChanged()
                                            throws IOException
Implement this method to support openIfChanged(DirectoryReader). If this reader does not support reopen, return null, so client code is happy. This should be consistent with isCurrent() (should always return true) if reopen is not supported.

Returns:
null if there are no changes; else, a new DirectoryReader instance.
Throws:
IOException - if there is a low-level IO error

doOpenIfChanged

protected abstract DirectoryReader doOpenIfChanged(IndexCommit commit)
                                            throws IOException
Implement this method to support openIfChanged(DirectoryReader,IndexCommit). If this reader does not support reopen from a specific IndexCommit, throw UnsupportedOperationException.

Returns:
null if there are no changes; else, a new DirectoryReader instance.
Throws:
IOException - if there is a low-level IO error

doOpenIfChanged

protected abstract DirectoryReader doOpenIfChanged(IndexWriter writer,
                                                   boolean applyAllDeletes)
                                            throws IOException
Implement this method to support openIfChanged(DirectoryReader,IndexWriter,boolean). If this reader does not support reopen from IndexWriter, throw UnsupportedOperationException.

Returns:
null if there are no changes; else, a new DirectoryReader instance.
Throws:
IOException - if there is a low-level IO error

getVersion

public abstract long getVersion()
Version number when this IndexReader was opened.

This method returns the version recorded in the commit that the reader opened. This version is advanced every time a change is made with IndexWriter.


isCurrent

public abstract boolean isCurrent()
                           throws IOException
Check whether any new changes have occurred to the index since this reader was opened.

If this reader was created by calling open(org.apache.lucene.store.Directory), then this method checks if any further commits (see IndexWriter.commit()) have occurred in the directory.

If instead this reader is a near real-time reader (ie, obtained by a call to open(IndexWriter,boolean), or by calling openIfChanged(org.apache.lucene.index.DirectoryReader) on a near real-time reader), then this method checks if either a new commit has occurred, or any new uncommitted changes have taken place via the writer. Note that even if the writer has only performed merging, this method will still return false.

In any event, if this returns false, you should call openIfChanged(org.apache.lucene.index.DirectoryReader) to get a new reader that sees the changes.

Throws:
IOException - if there is a low-level IO error

getIndexCommit

public abstract IndexCommit getIndexCommit()
                                    throws IOException
Expert: return the IndexCommit that this reader has opened.

Throws:
IOException
WARNING: This API is experimental and might change in incompatible ways in the next release.


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