Module org.apache.jena.serviceplugins
Package org.apache.jena.sparql.service.enhancer.claimingcache

Interface Ref<T>

Type Parameters:
T - The value type stored in this reference.
All Superinterfaces:
AutoCloseable
All Known Subinterfaces:
RefDelegate<T,R>, RefFuture<T>
All Known Implementing Classes:
RefDelegateBase, RefFutureImpl, RefImpl
public interface Ref<T> extends AutoCloseable
Interface for nested references. References allow for sharing an entity across several clients and deferring the release of that entity's resources immediately to the point in time when the last reference is released. The main use case is for memory paging such that if several threads request the same page only one physical buffer is handed out from a cache - conversely, as long as a page is still in used by a client, cache eviction and synchronization may be suppressed. Terminology:
  • A reference is closed when close() was called; open otherwise.
  • A reference is alive when it is open and/or any of the child refs acquired from it are still alive.
  • A reference is released (dead) as soon it is no longer alive. This immediately triggers its release action.
Implementation note: At present the alive-check and release action are assumed to run synchronously. As such there is no transition phase ('dying' or 'releasing'). This could be added in the future.

  • Method Details

    • getRootRef

      Ref<T> getRootRef()
      Get the root reference

    • get

      T get()
      Get the referent only iff this ref instance has not yet been closed. This method fails for closed alive refs. A closed reference is alive if it has unclosed child references. For most use cases the referent should be accessed using this method.
      Returns:
      The referent

    • getSynchronizer

      Object getSynchronizer()
      Return the object on which reference acquisition, release and the close action are synchronized on.

    • acquire

      Ref<T> acquire(Object purpose)
      Acquire a new reference with a given comment object Acquiration fails if isAlive() returns false

    • acquire

      default Ref<T> acquire()

    • isAlive

      boolean isAlive()
      A reference may itself be closed, but references to it may keep it alive
      Returns:
      true iff either this reference is not closed or there exists any acquired reference.

    • isClosed

      boolean isClosed()
      Check whether this reference is closed

    • close

      void close()
      Specified by:
      close in interface AutoCloseable

    • getAcquisitionStackTrace

      StackTraceElement[] getAcquisitionStackTrace()
      Optional operation. References may expose where they were acquired.

    • getCloseStackTrace

      StackTraceElement[] getCloseStackTrace()
      Optional operation. References may expose where they were closed was called.

    • getCloseTriggerStackTrace

      StackTraceElement[] getCloseTriggerStackTrace()
      Optional operation. References may expose where they were close was triggered upon release.

    • acquireMapped

      default <X> Ref<X> acquireMapped(Function<? super T,? extends X> mapper)
      Return a Ref with a new referent obtained by mapping this ref's value with mapper. Closing the returned Ref closes the original one. Synchronizes on the same object as this ref.