Class ReferenceManager<G>
- All Implemented Interfaces:
Closeable,AutoCloseable
- Direct Known Subclasses:
ReaderManager,SearcherManager
ReferenceManager implementations for their maybeRefresh() semantics.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic interfaceUse to receive notification when a refresh has finished. -
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionfinal Gacquire()Obtain the current reference.voidaddListener(ReferenceManager.RefreshListener listener) Adds a listener, to be notified when a reference is refreshed/swapped.protected voidCalled after close(), so subclass can free any resources.protected voidCalled after a refresh was attempted, regardless of whether a new reference was in fact created.final voidclose()Closes this ReferenceManager to prevent futureacquiring.protected abstract voidDecrement reference counting on the given reference.protected abstract intgetRefCount(G reference) Returns the current reference count of the given reference.final booleanYou must call this (ormaybeRefreshBlocking()), periodically, if you want thatacquire()will return refreshed instances.final voidYou must call this (ormaybeRefresh()), periodically, if you want thatacquire()will return refreshed instances.protected abstract GrefreshIfNeeded(G referenceToRefresh) Refresh the given reference if needed.final voidRelease the reference previously obtained viaacquire().voidRemove a listener added withaddListener(RefreshListener).protected abstract booleanTry to increment reference counting on the given reference.
-
Field Details
-
current
-
-
Constructor Details
-
ReferenceManager
public ReferenceManager()
-
-
Method Details
-
decRef
Decrement reference counting on the given reference.- Throws:
IOException- if reference decrement on the given resource failed.
-
refreshIfNeeded
Refresh the given reference if needed. Returnsnullif no refresh was needed, otherwise a new refreshed reference.- Throws:
AlreadyClosedException- if the reference manager has beenclosed.IOException- if the refresh operation failed
-
tryIncRef
Try to increment reference counting on the given reference. Return true if the operation was successful.- Throws:
AlreadyClosedException- if the reference manager has beenclosed.IOException
-
acquire
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 tonullto prevent accidental usage after it has been released.- Throws:
AlreadyClosedException- if the reference manager has beenclosed.IOException
-
close
Closes this ReferenceManager to prevent futureacquiring. A reference manager should be closed if the reference to the managed resource should be disposed or the application using theReferenceManageris shutting down. The managed resource might not be released immediately, if theReferenceManageruser is holding on to a previouslyacquiredreference. 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
acquirenew references from this manager once this method has been called.Acquiringa resource on a closedReferenceManagerwill throw anAlreadyClosedException.- Specified by:
closein interfaceAutoCloseable- Specified by:
closein interfaceCloseable- Throws:
IOException- if the underlying reader of the current reference could not be closed
-
getRefCount
Returns the current reference count of the given reference. -
afterClose
Called after close(), so subclass can free any resources.- Throws:
IOException- if the after close operation in a sub-class throws anIOException
-
maybeRefresh
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 anIOExceptionAlreadyClosedException- if the reference manager has beenclosed.
-
maybeRefreshBlocking
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 anIOExceptionAlreadyClosedException- if the reference manager has beenclosed.
-
afterMaybeRefresh
Called after a refresh was attempted, regardless of whether a new reference was in fact created.- Throws:
IOException- if a low level I/O exception occurs
-
release
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
Adds a listener, to be notified when a reference is refreshed/swapped. -
removeListener
Remove a listener added withaddListener(RefreshListener).
-