org.apache.lucene.search

Class SearcherManager

java.lang.Object

org.apache.lucene.search.ReferenceManager<IndexSearcher>

org.apache.lucene.search.SearcherManager

All Implemented Interfaces:

Closeable, AutoCloseable

public final class SearcherManager
extends ReferenceManager<IndexSearcher>

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 ReferenceManager.acquire() to obtain the current searcher, and ReferenceManager.release(G) 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 ReferenceManager.maybeRefresh(). While it's possible to call this just before running each query, this is discouraged since it penalizes the unlucky queries that need to refresh. It's better to use a separate background thread, that periodically calls ReferenceManager.maybeRefresh(). Finally, be sure to call ReferenceManager.close() once you are done.

See Also:

SearcherFactory

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

Nested Class Summary

Nested classes/interfaces inherited from class org.apache.lucene.search.ReferenceManager

ReferenceManager.RefreshListener

Field Summary

Fields inherited from class org.apache.lucene.search.ReferenceManager

current

Constructor Summary

Constructors

Constructor and Description
SearcherManager(DirectoryReader reader, SearcherFactory searcherFactory) Creates and returns a new SearcherManager from an existing DirectoryReader.
SearcherManager(Directory dir, SearcherFactory searcherFactory) Creates and returns a new SearcherManager from the given Directory.
SearcherManager(IndexWriter writer, boolean applyAllDeletes, boolean writeAllDeletes, SearcherFactory searcherFactory) Expert: creates and returns a new SearcherManager from the given IndexWriter, controlling whether past deletions should be applied.
SearcherManager(IndexWriter writer, SearcherFactory searcherFactory) Creates and returns a new SearcherManager from the given IndexWriter.

Method Summary

Modifier and Type	Method and Description
protected void	decRef(IndexSearcher reference) Decrement reference counting on the given reference.
protected int	getRefCount(IndexSearcher reference) Returns the current reference count of the given reference.
static IndexSearcher	getSearcher(SearcherFactory searcherFactory, IndexReader reader, IndexReader previousReader) Expert: creates a searcher from the provided IndexReader using the provided SearcherFactory.
boolean	isSearcherCurrent() Returns true if no changes have occured since this searcher ie.
protected IndexSearcher	refreshIfNeeded(IndexSearcher referenceToRefresh) Refresh the given reference if needed.
protected boolean	tryIncRef(IndexSearcher reference) Try to increment reference counting on the given reference.

Methods inherited from class org.apache.lucene.search.ReferenceManager

acquire, addListener, afterClose, afterMaybeRefresh, close, maybeRefresh, maybeRefreshBlocking, release, removeListener

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,
                       SearcherFactory searcherFactory)
                throws IOException

Creates and returns a new SearcherManager from the given IndexWriter.

Parameters:

writer - the IndexWriter to open the IndexReader from.

searcherFactory - An optional SearcherFactory. Pass null if you don't require the searcher to be warmed before going live or other custom behavior.

Throws:

IOException - if there is a low-level I/O error

SearcherManager

public SearcherManager(IndexWriter writer,
                       boolean applyAllDeletes,
                       boolean writeAllDeletes,
                       SearcherFactory searcherFactory)
                throws IOException

Expert: creates and returns a new SearcherManager from the given IndexWriter, controlling whether past deletions should be applied.

Parameters:

writer - the IndexWriter to open the IndexReader from.

applyAllDeletes - If true, all buffered deletes will be applied (made visible) in the IndexSearcher / DirectoryReader. 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 DirectoryReader.openIfChanged(DirectoryReader, IndexWriter, boolean).

writeAllDeletes - If true, new deletes will be forcefully written to index files.

searcherFactory - An optional SearcherFactory. Pass null if you don't require the searcher to be warmed before going live or other custom behavior.

Throws:

IOException - if there is a low-level I/O error

SearcherManager

public SearcherManager(Directory dir,
                       SearcherFactory searcherFactory)
                throws IOException

Creates and returns a new SearcherManager from the given Directory.

Parameters:

dir - the directory to open the DirectoryReader on.

searcherFactory - An optional SearcherFactory. Pass null if you don't require the searcher to be warmed before going live or other custom behavior.

Throws:

IOException - if there is a low-level I/O error

SearcherManager

public SearcherManager(DirectoryReader reader,
                       SearcherFactory searcherFactory)
                throws IOException

Creates and returns a new SearcherManager from an existing DirectoryReader. Note that this steals the incoming reference.

Parameters:

reader - the DirectoryReader.

searcherFactory - An optional SearcherFactory. Pass null if you don't require the searcher to be warmed before going live or other custom behavior.

Throws:

IOException - if there is a low-level I/O error

Method Detail

decRef

protected void decRef(IndexSearcher reference)
               throws IOException

Description copied from class: ReferenceManager

Decrement reference counting on the given reference.

Specified by:

decRef in class ReferenceManager<IndexSearcher>

Throws:

IOException - if reference decrement on the given resource failed.

refreshIfNeeded

protected IndexSearcher refreshIfNeeded(IndexSearcher referenceToRefresh)
                                 throws IOException

Description copied from class: ReferenceManager

Refresh the given reference if needed. Returns null if no refresh was needed, otherwise a new refreshed reference.

Specified by:

refreshIfNeeded in class ReferenceManager<IndexSearcher>

Throws:

IOException - if the refresh operation failed

tryIncRef

protected boolean tryIncRef(IndexSearcher reference)

Description copied from class: ReferenceManager

Try to increment reference counting on the given reference. Return true if the operation was successful.

Specified by:

tryIncRef in class ReferenceManager<IndexSearcher>

getRefCount

protected int getRefCount(IndexSearcher reference)

Description copied from class: ReferenceManager

Returns the current reference count of the given reference.

Specified by:

getRefCount in class ReferenceManager<IndexSearcher>

isSearcherCurrent

public boolean isSearcherCurrent()
                          throws IOException

Returns true if no changes have occured since this searcher ie. reader was opened, otherwise false.

Throws:

IOException

See Also:

DirectoryReader.isCurrent()

getSearcher

public static IndexSearcher getSearcher(SearcherFactory searcherFactory,
                                        IndexReader reader,
                                        IndexReader previousReader)
                                 throws IOException

Expert: creates a searcher from the provided IndexReader using the provided SearcherFactory. NOTE: this decRefs incoming reader on throwing an exception.

Throws:

IOException