org.apache.lucene.search
Class SearcherManager

java.lang.Object
  extended by org.apache.lucene.search.SearcherManager

public final class SearcherManager
extends Object

Utility class to safely share IndexSearcher instances across multiple threads, while periodically reopening. This class ensures each searcher is closed only once all threads have finished using it.

Use acquire() to obtain the current searcher, and release(org.apache.lucene.search.IndexSearcher) to release it, like this:

 IndexSearcher s = manager.acquire();
 try {
   // Do searching, doc retrieval, etc. with s
 } finally {
   manager.release(s);
 }
 // Do not use s after this!
 s = null;
 

In addition you should periodically call maybeReopen(). While it's possible to call this just before running each query, this is discouraged since it penalizes the unlucky queries that do the reopen. It's better to use a separate background thread, that periodically calls maybeReopen. Finally, be sure to call close() once you are done.

NOTE: if you have an IndexWriter, it's better to use NRTManager since that class pulls near-real-time readers from the IndexWriter.

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

Constructor Summary
SearcherManager(Directory dir, SearcherWarmer warmer, ExecutorService es)
          Creates and returns a new SearcherManager from the given Directory.
SearcherManager(IndexWriter writer, boolean applyAllDeletes, SearcherWarmer warmer, ExecutorService es)
          Creates and returns a new SearcherManager from the given IndexWriter.
 
Method Summary
 IndexSearcher acquire()
          Obtain the current IndexSearcher.
 void close()
          Close this SearcherManager to future searching.
 boolean isSearcherCurrent()
          Returns true if no changes have occured since this searcher ie.
 boolean maybeReopen()
          You must call this, periodically, to perform a reopen.
 void release(IndexSearcher searcher)
          Release the searcher previously obtained with acquire().
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SearcherManager

public SearcherManager(IndexWriter writer,
                       boolean applyAllDeletes,
                       SearcherWarmer warmer,
                       ExecutorService es)
                throws IOException
Creates and returns a new SearcherManager from the given IndexWriter.

Parameters:
writer - the IndexWriter to open the IndexReader from.
applyAllDeletes - If true, all buffered deletes will be applied (made visible) in the IndexSearcher / IndexReader. If false, the deletes may or may not be 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. See IndexReader.openIfChanged(IndexReader, IndexWriter, boolean).
warmer - An optional SearcherWarmer. Pass null if you don't require the searcher to warmed before going live. If this is non-null then a merged segment warmer is installed on the provided IndexWriter's config.
es - An optional ExecutorService so different segments can be searched concurrently (see IndexSearcher.IndexSearcher(IndexReader,ExecutorService). Pass null to search segments sequentially.
Throws:
IOException

SearcherManager

public SearcherManager(Directory dir,
                       SearcherWarmer warmer,
                       ExecutorService es)
                throws IOException
Creates and returns a new SearcherManager from the given Directory.

Parameters:
dir - the directory to open the IndexReader on.
warmer - An optional SearcherWarmer. Pass null if you don't require the searcher to warmed before going live. If this is non-null then a merged segment warmer is installed on the provided IndexWriter's config.
es - And optional ExecutorService so different segments can be searched concurrently (see IndexSearcher.IndexSearcher(IndexReader,ExecutorService). Pass null to search segments sequentially.
Throws:
IOException
Method Detail

maybeReopen

public boolean maybeReopen()
                    throws IOException
You must call this, periodically, to perform a reopen. This calls IndexReader.openIfChanged(IndexReader) with the underlying reader, and if that returns a new reader, it's warmed (if you provided a SearcherWarmer and then swapped into production.

Threads: it's fine for more than one thread to call this at once. Only the first thread will attempt the reopen; subsequent threads will see that another thread is already handling reopen and will return immediately. Note that this means if another thread is already reopening then subsequent threads will return right away without waiting for the reader reopen to complete.

This method returns true if a new reader was in fact opened or if the current searcher has no pending changes.

Throws:
IOException

isSearcherCurrent

public boolean isSearcherCurrent()
                          throws CorruptIndexException,
                                 IOException
Returns true if no changes have occured since this searcher ie. reader was opened, otherwise false.

Throws:
CorruptIndexException
IOException
See Also:
IndexReader.isCurrent()

release

public void release(IndexSearcher searcher)
             throws IOException
Release the searcher previously obtained with acquire().

NOTE: it's safe to call this after close().

Throws:
IOException

close

public void close()
           throws IOException
Close this SearcherManager to future searching. Any searches still in process in other threads won't be affected, and they should still call release(org.apache.lucene.search.IndexSearcher) after they are done.

Throws:
IOException

acquire

public IndexSearcher acquire()
Obtain the current IndexSearcher. You must match every call to acquire with one call to release(org.apache.lucene.search.IndexSearcher); it's best to do so in a finally clause.



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