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:
    Closeable, AutoCloseable
  Direct Known Subclasses:
    ReaderManager, SearcherManager

      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 of `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 Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `ReferenceManager.RefreshListener` Use to receive notification when a refresh has finished.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected G` | `current`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ReferenceManager()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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.
    `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.
    `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

    - #### current

          protected volatile G current

  - ### Constructor Detail

    - #### ReferenceManager

          public ReferenceManager()

  - ### Method Detail

    - #### decRef

          protected abstract void decRef(G reference)
                                  throws IOException

      Decrement reference counting on the given reference.
      Throws:
        `IOException` - if reference decrement on the given resource failed.

    - #### refreshIfNeeded

          protected abstract G refreshIfNeeded(G referenceToRefresh)
                                        throws 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`.
        `IOException` - if the refresh operation failed

    - #### tryIncRef

          protected abstract boolean tryIncRef(G reference)
                                        throws 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`.
        `IOException`

    - #### acquire

          public final G acquire()
                          throws 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`.
        `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 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 `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Throws:
        `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 IOException

      Called after close(), so subclass can free any resources.
      Throws:
        `IOException` - if the after close operation in a sub-class throws an `IOException`

    - #### maybeRefresh

          public final boolean maybeRefresh()
                                     throws 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:
        `IOException` - if refreshing the resource causes an `IOException`
        `AlreadyClosedException` - if the reference manager has been `closed`.

    - #### maybeRefreshBlocking

          public final void maybeRefreshBlocking()
                                          throws 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:
        `IOException` - if refreshing the resource causes an `IOException`
        `AlreadyClosedException` - if the reference manager has been `closed`.

    - #### afterMaybeRefresh

          protected void afterMaybeRefresh()
                                    throws IOException

      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

          public final void release(G reference)
                             throws IOException

      Release the reference previously obtained via `acquire()`.

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

      Throws:
        `IOException` - if the release operation on the given resource throws an `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)`.

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.