Package org.apache.lucene.search

Class ReferenceManager<G>

java.lang.Object

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

Type Parameters:

G - the concrete type that will be acquired and released.

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

Direct Known Subclasses:

ReaderManager, SearcherManager

public abstract class ReferenceManager<G>
extends java.lang.Object
implements java.io.Closeable

Utility class to safely share instances of a certain type across multiple threads, while periodically refreshing them. This class ensures each reference is closed only once all threads have finished using it. It is recommended to consult the documentation of ReferenceManager implementations for their maybeRefresh() semantics.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ReferenceManager.RefreshListener	Use to receive notification when a refresh has finished.

Field Summary

Fields

Modifier and Type	Field	Description
protected G	current
private static java.lang.String	REFERENCE_MANAGER_IS_CLOSED_MSG
private java.util.List<ReferenceManager.RefreshListener>	refreshListeners
private java.util.concurrent.locks.Lock	refreshLock

Constructor Summary

Constructors

Constructor	Description
ReferenceManager()

Method Summary

Modifier and Type	Method	Description
G	acquire()	Obtain the current reference.
void	addListener(ReferenceManager.RefreshListener listener)	Adds a listener, to be notified when a reference is refreshed/swapped.
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.
void	close()	Closes this ReferenceManager to prevent future acquiring.
protected abstract void	decRef(G reference)	Decrement reference counting on the given reference.
private void	doMaybeRefresh()
private void	ensureOpen()
protected abstract int	getRefCount(G reference)	Returns the current reference count of the given reference.
boolean	maybeRefresh()	You must call this (or maybeRefreshBlocking()), periodically, if you want that acquire() will return refreshed instances.
void	maybeRefreshBlocking()	You must call this (or maybeRefresh()), periodically, if you want that acquire() will return refreshed instances.
private void	notifyRefreshListenersBefore()
private void	notifyRefreshListenersRefreshed(boolean didRefresh)
protected abstract G	refreshIfNeeded(G referenceToRefresh)	Refresh the given reference if needed.
void	release(G reference)	Release the reference previously obtained via acquire().
void	removeListener(ReferenceManager.RefreshListener listener)	Remove a listener added with addListener(RefreshListener).
private void	swapReference(G newReference)
protected abstract boolean	tryIncRef(G reference)	Try to increment reference counting on the given reference.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

REFERENCE_MANAGER_IS_CLOSED_MSG

private static final java.lang.String REFERENCE_MANAGER_IS_CLOSED_MSG

See Also:

Constant Field Values

current

protected volatile G current

refreshLock

private final java.util.concurrent.locks.Lock refreshLock

refreshListeners

private final java.util.List<ReferenceManager.RefreshListener> refreshListeners

Constructor Detail

ReferenceManager

public ReferenceManager()

Method Detail

ensureOpen

private void ensureOpen()

swapReference

private void swapReference(G newReference)
                    throws java.io.IOException

Throws:

java.io.IOException

decRef

protected abstract void decRef(G reference)
                        throws java.io.IOException

Decrement reference counting on the given reference.

Throws:

java.io.IOException - if reference decrement on the given resource failed.

refreshIfNeeded

protected abstract G refreshIfNeeded(G referenceToRefresh)
                              throws java.io.IOException

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

Throws:

AlreadyClosedException - if the reference manager has been closed.

java.io.IOException - if the refresh operation failed

tryIncRef

protected abstract boolean tryIncRef(G reference)
                              throws java.io.IOException

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

Throws:

AlreadyClosedException - if the reference manager has been closed.

java.io.IOException

acquire

public final G acquire()
                throws java.io.IOException

Obtain the current reference. You must match every call to acquire with one call to release(G); it's best to do so in a finally clause, and set the reference to null to prevent accidental usage after it has been released.

Throws:

AlreadyClosedException - if the reference manager has been closed.

java.io.IOException

close

public final void close()
                 throws java.io.IOException

Closes this ReferenceManager to prevent future acquiring. A reference manager should be closed if the reference to the managed resource should be disposed or the application using the ReferenceManager is shutting down. The managed resource might not be released immediately, if the ReferenceManager user is holding on to a previously acquired reference. The resource will be released once when the last reference is released. Those references can still be used as if the manager was still active.

Applications should not acquire new references from this manager once this method has been called. Acquiring a resource on a closed ReferenceManager will throw an AlreadyClosedException.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException - if the underlying reader of the current reference could not be closed

getRefCount

protected abstract int getRefCount(G reference)

Returns the current reference count of the given reference.

afterClose

protected void afterClose()
                   throws java.io.IOException

Called after close(), so subclass can free any resources.

Throws:

java.io.IOException - if the after close operation in a sub-class throws an IOException

doMaybeRefresh

private void doMaybeRefresh()
                     throws java.io.IOException

Throws:

java.io.IOException

maybeRefresh

public final boolean maybeRefresh()
                           throws java.io.IOException

You must call this (or maybeRefreshBlocking()), periodically, if you want that acquire() will return refreshed instances.

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

If this method returns true it means the calling thread either refreshed or that there were no changes to refresh. If it returns false it means another thread is currently refreshing.

Throws:

java.io.IOException - if refreshing the resource causes an IOException

AlreadyClosedException - if the reference manager has been closed.

maybeRefreshBlocking

public final void maybeRefreshBlocking()
                                throws java.io.IOException

You must call this (or maybeRefresh()), periodically, if you want that acquire() will return refreshed instances.

Threads: unlike maybeRefresh(), if another thread is currently refreshing, this method blocks until that thread completes. It is useful if you want to guarantee that the next call to acquire() will return a refreshed instance. Otherwise, consider using the non-blocking maybeRefresh().

Throws:

java.io.IOException - if refreshing the resource causes an IOException

AlreadyClosedException - if the reference manager has been closed.

afterMaybeRefresh

protected void afterMaybeRefresh()
                          throws java.io.IOException

Called after a refresh was attempted, regardless of whether a new reference was in fact created.

Throws:

java.io.IOException - if a low level I/O exception occurs

release

public final void release(G reference)
                   throws java.io.IOException

Release the reference previously obtained via acquire().

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

Throws:

java.io.IOException - if the release operation on the given resource throws an IOException

notifyRefreshListenersBefore

private void notifyRefreshListenersBefore()
                                   throws java.io.IOException

Throws:

java.io.IOException

notifyRefreshListenersRefreshed

private void notifyRefreshListenersRefreshed(boolean didRefresh)
                                      throws java.io.IOException

Throws:

java.io.IOException

addListener

public void addListener(ReferenceManager.RefreshListener listener)

Adds a listener, to be notified when a reference is refreshed/swapped.

removeListener

public void removeListener(ReferenceManager.RefreshListener listener)

Remove a listener added with addListener(RefreshListener).