Class ReferenceManager<G>
- java.lang.Object
-
- org.apache.lucene.search.ReferenceManager<G>
-
- All Implemented Interfaces:
Closeable
,AutoCloseable
- Direct Known Subclasses:
ReaderManager
,SearcherManager
,SearcherTaxonomyManager
public abstract class ReferenceManager<G> extends Object implements 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 ofReferenceManager
implementations for theirmaybeRefresh()
semantics.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static interface
ReferenceManager.RefreshListener
Use to receive notification when a refresh has finished.
-
Constructor Summary
Constructors Constructor Description ReferenceManager()
-
Method Summary
All Methods Instance Methods Concrete Methods 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.void
close()
Closes this ReferenceManager to prevent futureacquiring
.boolean
maybeRefresh()
You must call this (ormaybeRefreshBlocking()
), periodically, if you want thatacquire()
will return refreshed instances.void
maybeRefreshBlocking()
You must call this (ormaybeRefresh()
), periodically, if you want thatacquire()
will return refreshed instances.void
release(G reference)
Release the reference previously obtained viaacquire()
.void
removeListener(ReferenceManager.RefreshListener listener)
Remove a listener added withaddListener(RefreshListener)
.
-
-
-
Method Detail
-
acquire
public final G acquire() throws IOException
Obtain the current reference. You must match every call to acquire with one call torelease(G)
; it's best to do so in a finally clause, and set the reference tonull
to prevent accidental usage after it has been released.- Throws:
AlreadyClosedException
- if the reference manager has beenclosed
.IOException
-
close
public final void close() throws 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 theReferenceManager
is shutting down. The managed resource might not be released immediately, if theReferenceManager
user is holding on to a previouslyacquired
reference. The resource will be released once when the last reference isreleased
. 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 closedReferenceManager
will throw anAlreadyClosedException
.- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceCloseable
- Throws:
IOException
- if the underlying reader of the current reference could not be closed
-
maybeRefresh
public final boolean maybeRefresh() throws IOException
You must call this (ormaybeRefreshBlocking()
), periodically, if you want thatacquire()
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:
IOException
- if refreshing the resource causes anIOException
AlreadyClosedException
- if the reference manager has beenclosed
.
-
maybeRefreshBlocking
public final void maybeRefreshBlocking() throws IOException
You must call this (ormaybeRefresh()
), periodically, if you want thatacquire()
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 toacquire()
will return a refreshed instance. Otherwise, consider using the non-blockingmaybeRefresh()
.- Throws:
IOException
- if refreshing the resource causes anIOException
AlreadyClosedException
- if the reference manager has beenclosed
.
-
release
public final void release(G reference) throws IOException
Release the reference previously obtained viaacquire()
.NOTE: it's safe to call this after
close()
.- Throws:
IOException
- if the release operation on the given resource throws anIOException
-
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 withaddListener(RefreshListener)
.
-
-