/// <summary>
/// Expert: If there changes (committed or not) in the
/// <see cref="IndexWriter"/> versus what the provided reader is
/// searching, then open and return a new
/// <see cref="IndexReader"/> searching both committed and uncommitted
/// changes from the writer; else, return <c>null</c> (though, the
/// current implementation never returns <c>null</c>).
///
/// <para/>This provides "near real-time" searching, in that
/// changes made during an <see cref="IndexWriter"/> session can be
/// quickly made available for searching without closing
/// the writer nor calling <see cref="IndexWriter.Commit()"/>.
///
/// <para>It's <i>near</i> real-time because there is no hard
/// guarantee on how quickly you can get a new reader after
/// making changes with <see cref="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.</para>
///
/// <para>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.</para>
///
/// <para>For lower latency on reopening a reader, you should
/// call <see cref="LiveIndexWriterConfig.MergedSegmentWarmer"/> (on <see cref="IndexWriterConfig"/>) 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. </para>
///
/// <para>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.</para>
///
/// <para><b>NOTE</b>: Once the writer is disposed, any
/// outstanding readers may continue to be used. However,
/// if you attempt to reopen any of those readers, you'll
/// hit an <see cref="System.ObjectDisposedException"/>.</para>
///
/// @lucene.experimental
/// </summary>
/// <returns> <see cref="DirectoryReader"/> that covers entire index plus all
/// changes made so far by this <see cref="IndexWriter"/> instance, or
/// <c>null</c> if there are no new changes
/// </returns>
/// <param name="writer"> The <see cref="IndexWriter"/> to open from
/// </param>
/// <param name="applyAllDeletes"> If <c>true</c>, all buffered deletes will
/// be applied (made visible) in the returned reader. If
/// <c>false</c>, the deletes are not applied but remain buffered
/// (in <see cref="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 <c>false</c>.
/// </param>
/// <exception cref="IOException"> if there is a low-level IO error </exception>
public static DirectoryReader OpenIfChanged(DirectoryReader oldReader, IndexWriter writer, bool applyAllDeletes)
{
DirectoryReader newReader = oldReader.DoOpenIfChanged(writer, applyAllDeletes);
Debug.Assert(newReader != oldReader);
return(newReader);
}
/// <summary>
/// If the index has changed since the provided reader was
/// opened, open and return a new reader; else, return
/// <c>null</c>. The new reader, if not <c>null</c>, will be the same
/// type of reader as the previous one, ie a near-real-time (NRT) reader
/// will open a new NRT reader, a <see cref="MultiReader"/> will open a
/// new <see cref="MultiReader"/>, etc.
///
/// <para/>This method is typically far less costly than opening a
/// fully new <see cref="DirectoryReader"/> as it shares
/// resources (for example sub-readers) with the provided
/// <see cref="DirectoryReader"/>, when possible.
///
/// <para/>The provided reader is not disposed (you are responsible
/// for doing so); if a new reader is returned you also
/// must eventually dispose it. Be sure to never dispose a
/// reader while other threads are still using it; see
/// <see cref="Search.SearcherManager"/> to simplify managing this.
/// </summary>
/// <exception cref="CorruptIndexException"> if the index is corrupt </exception>
/// <exception cref="IOException"> if there is a low-level IO error </exception>
/// <returns> <c>null</c> if there are no changes; else, a new
/// <see cref="DirectoryReader"/> instance which you must eventually dispose </returns>
public static DirectoryReader OpenIfChanged(DirectoryReader oldReader)
{
DirectoryReader newReader = oldReader.DoOpenIfChanged();
Debug.Assert(newReader != oldReader);
return(newReader);
}
/// <summary>
/// If the <see cref="Index.IndexCommit"/> differs from what the
/// provided reader is searching, open and return a new
/// reader; else, return <c>null</c>.
/// </summary>
/// <seealso cref="OpenIfChanged(DirectoryReader)"/>
public static DirectoryReader OpenIfChanged(DirectoryReader oldReader, IndexCommit commit)
{
DirectoryReader newReader = oldReader.DoOpenIfChanged(commit);
Debug.Assert(newReader != oldReader);
return(newReader);
}
/// <summary>
/// If the <see cref="Index.IndexCommit"/> differs from what the
/// provided reader is searching, open and return a new
/// reader; else, return <c>null</c>.
/// </summary>
/// <seealso cref="OpenIfChanged(DirectoryReader)"/>
public static DirectoryReader OpenIfChanged(DirectoryReader oldReader, IndexCommit commit)
{
DirectoryReader newReader = oldReader.DoOpenIfChanged(commit);
if (Debugging.AssertsEnabled)
{
Debugging.Assert(newReader != oldReader);
}
return(newReader);
}
protected internal override sealed DirectoryReader DoOpenIfChanged()
{
return(WrapDirectoryReader(m_input.DoOpenIfChanged()));
}
