org.apache.lucene.search

## Class NRTManager

- java.lang.Object
- - org.apache.lucene.search.ReferenceManager<IndexSearcher>
  - - org.apache.lucene.search.NRTManager

All Implemented Interfaces:
  Closeable, AutoCloseable

    public final class NRTManager
    extends ReferenceManager<IndexSearcher>

Utility class to manage sharing near-real-time searchers across multiple searching thread. The difference vs SearcherManager is that this class enables individual requests to wait until specific indexing changes are visible.

You must create an IndexWriter, then create a `NRTManager.TrackingIndexWriter` from it, and pass that to the NRTManager. You may want to create two NRTManagers, once that always applies deletes on refresh and one that does not. In this case you should use a single `NRTManager.TrackingIndexWriter` instance for both.

Then, use `ReferenceManager.acquire()` to obtain the `IndexSearcher`, and `ReferenceManager.release(G)` (ideally, from within a `finally` clause) to release it.

NOTE: to use this class, you must call `ReferenceManager.maybeRefresh()` periodically. The `NRTManagerReopenThread` is a simple class to do this on a periodic basis, and reopens more quickly if a request is waiting. If you implement your own reopener, be sure to call `addWaitingListener(org.apache.lucene.search.NRTManager.WaitingListener)` so your reopener is notified when a caller is waiting for a specific generation searcher.

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

### Nested Class Summary

Nested Classes
`static class` `NRTManager.TrackingIndexWriter` Class that tracks changes to a delegated IndexWriter.
`static interface` `NRTManager.WaitingListener` NRTManager invokes this interface to notify it when a caller is waiting for a specific generation searcher to be visible.

### 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
`NRTManager(NRTManager.TrackingIndexWriter writer, SearcherFactory searcherFactory)` Create new NRTManager.
`NRTManager(NRTManager.TrackingIndexWriter writer, SearcherFactory searcherFactory, boolean applyAllDeletes)` Expert: just like `NRTManager(TrackingIndexWriter,SearcherFactory)`, but you can also specify whether each reopened searcher must apply deletes.

### Method Summary

Methods
`void` `addWaitingListener(NRTManager.WaitingListener l)` Adds a listener, to be notified when a caller is waiting for a specific generation searcher to be visible.
`protected void` `afterClose()` Called after close(), so subclass can free any resources.
`protected void` `afterMaybeRefresh()` Called after a refresh was attempted, regardless of whether a new reference was in fact created.
`protected void` `decRef(IndexSearcher reference)` Decrement reference counting on the given reference.
`long` `getCurrentSearchingGen()` Returns generation of current searcher.
`boolean` `isSearcherCurrent()` Returns `true` if no changes have occured since this searcher ie.
`protected IndexSearcher` `refreshIfNeeded(IndexSearcher referenceToRefresh)` Refresh the given reference if needed.
`void` `removeWaitingListener(NRTManager.WaitingListener l)` Remove a listener added with `addWaitingListener(org.apache.lucene.search.NRTManager.WaitingListener)`.
`protected boolean` `tryIncRef(IndexSearcher reference)` Try to increment reference counting on the given reference.
`void` `waitForGeneration(long targetGen)` Waits for the target generation to become visible in the searcher.
`void` `waitForGeneration(long targetGen, long time, TimeUnit unit)` Waits for the target generation to become visible in the searcher.

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

`acquire, addListener, 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

#### NRTManager

    public NRTManager(NRTManager.TrackingIndexWriter writer,
              SearcherFactory searcherFactory)
               throws IOException

Create new NRTManager.

Parameters:
  `writer` - TrackingIndexWriter to open near-real-time readers
  `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`

#### NRTManager

    public NRTManager(NRTManager.TrackingIndexWriter writer,
              SearcherFactory searcherFactory,
              boolean applyAllDeletes)
               throws IOException

Expert: just like `NRTManager(TrackingIndexWriter,SearcherFactory)`, but you can also specify whether each reopened searcher must apply deletes. This is useful for cases where certain uses can tolerate seeing some deleted docs, since reopen time is faster if deletes need not be applied.

Throws:
  `IOException`

### 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.

#### 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>`

#### addWaitingListener

    public void addWaitingListener(NRTManager.WaitingListener l)

Adds a listener, to be notified when a caller is waiting for a specific generation searcher to be visible.

#### removeWaitingListener

    public void removeWaitingListener(NRTManager.WaitingListener l)

Remove a listener added with `addWaitingListener(org.apache.lucene.search.NRTManager.WaitingListener)`.

#### waitForGeneration

    public void waitForGeneration(long targetGen)

Waits for the target generation to become visible in the searcher. If the current searcher is older than the target generation, this method will block until the searcher is reopened, by another via `ReferenceManager.maybeRefresh()` or until the `NRTManager` is closed.

Parameters:
  `targetGen` - the generation to wait for

#### waitForGeneration

    public void waitForGeneration(long targetGen,
                         long time,
                         TimeUnit unit)

Waits for the target generation to become visible in the searcher. If the current searcher is older than the target generation, this method will block until the searcher has been reopened by another thread via `ReferenceManager.maybeRefresh()`, the given waiting time has elapsed, or until the NRTManager is closed.

NOTE: if the waiting time elapses before the requested target generation is available the current `SearcherManager` is returned instead.

Parameters:
  `targetGen` - the generation to wait for
  `time` - the time to wait for the target generation
  `unit` - the waiting time's time unit

#### getCurrentSearchingGen

    public long getCurrentSearchingGen()

Returns generation of current searcher.

#### 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

#### afterMaybeRefresh

    protected void afterMaybeRefresh()

Description copied from class: `ReferenceManager`
Called after a refresh was attempted, regardless of whether a new reference was in fact created.

Overrides:
  `afterMaybeRefresh` in class `ReferenceManager<IndexSearcher>`

#### afterClose

    protected void afterClose()
                       throws IOException

Description copied from class: `ReferenceManager`
Called after close(), so subclass can free any resources.

Overrides:
  `afterClose` in class `ReferenceManager<IndexSearcher>`
Throws:
  `IOException` - if the after close operation in a sub-class throws an `IOException`

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