|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object org.apache.lucene.search.ReferenceManager<G>
G
- the concrete type that will be acquired
and
released
.public abstract class ReferenceManager<G>
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 | |
---|---|
static interface |
ReferenceManager.RefreshListener
Use to receive notification when a refresh has finished. |
Field Summary | |
---|---|
protected G |
current
|
Constructor Summary | |
---|---|
ReferenceManager()
|
Method Summary | |
---|---|
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. |
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. |
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) . |
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 |
---|
protected volatile G current
Constructor Detail |
---|
public ReferenceManager()
Method Detail |
---|
protected abstract void decRef(G reference) throws IOException
IOException
- if reference decrement on the given resource failed.protected abstract G refreshIfNeeded(G referenceToRefresh) throws IOException
null
if no refresh
was needed, otherwise a new refreshed reference.
AlreadyClosedException
- if the reference manager has been closed
.
IOException
- if the refresh operation failedprotected abstract boolean tryIncRef(G reference) throws IOException
AlreadyClosedException
- if the reference manager has been closed
.
IOException
public final G acquire() throws IOException
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.
AlreadyClosedException
- if the reference manager has been closed
.
IOException
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 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
.
close
in interface Closeable
IOException
- if the underlying reader of the current reference could not be closedprotected void afterClose() throws IOException
IOException
- if the after close operation in a sub-class throws an IOException
public final boolean maybeRefresh() throws IOException
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.
IOException
- if refreshing the resource causes an IOException
AlreadyClosedException
- if the reference manager has been closed
.public final void maybeRefreshBlocking() throws IOException
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()
.
IOException
- if refreshing the resource causes an IOException
AlreadyClosedException
- if the reference manager has been closed
.protected void afterMaybeRefresh() throws IOException
IOException
- if a low level I/O exception occurspublic final void release(G reference) throws IOException
acquire()
.
NOTE: it's safe to call this after close()
.
IOException
- if the release operation on the given resource throws an IOException
public void addListener(ReferenceManager.RefreshListener listener)
public void removeListener(ReferenceManager.RefreshListener listener)
addListener(RefreshListener)
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |