Package com.exonum.binding.core.proxy

Class AbstractCloseableNativeProxy

java.lang.Object
com.exonum.binding.core.proxy.AbstractNativeProxy
com.exonum.binding.core.proxy.AbstractCloseableNativeProxy
All Implemented Interfaces:
CloseableNativeProxy, java.lang.AutoCloseable
Direct Known Subclasses:
NodeProxy, TemporaryDb, TestKit
public abstract class AbstractCloseableNativeProxy
extends AbstractNativeProxy
implements CloseableNativeProxy
A proxy of a native object.

A native proxy references the corresponding native object by its implementation-specific handle. If handle is zero, the proxy is considered invalid and will not permit referencing any native object. It is perfectly possible to get an invalid proxy (e.g., if a native method fails to allocate a native object).

You must close a native proxy when it is no longer needed to release any resources it holds (e.g., destroy a native object). You may use a try-with-resources statement to do that in orderly fashion. When a proxy is closed, it becomes invalid.

  • Field Summary

    Fields inherited from class com.exonum.binding.core.proxy.AbstractNativeProxy

    nativeHandle

  • Constructor Summary

    Constructors 
    Modifier Constructor Description
    protected AbstractCloseableNativeProxy​(long nativeHandle, boolean dispose)
    Creates a native proxy.
    protected AbstractCloseableNativeProxy​(long nativeHandle, boolean dispose, AbstractCloseableNativeProxy referenced)
    Creates a native proxy.
    protected AbstractCloseableNativeProxy​(long nativeHandle, boolean dispose, java.util.Collection<AbstractCloseableNativeProxy> referenced)
    Creates a native proxy.

  • Method Summary

    Modifier and Type Method Description
    void close()
    Closes the native proxy and releases any native resources associated with this proxy.
    protected abstract void disposeInternal()
    Releases any resources owned by this proxy (e.g., the corresponding native object).
    protected long getNativeHandle()
    Returns a native implementation-specific handle if it may be safely used to access the native object.

    Methods inherited from class com.exonum.binding.core.proxy.AbstractNativeProxy

    isValidHandle

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • AbstractCloseableNativeProxy

      protected AbstractCloseableNativeProxy​(long nativeHandle, boolean dispose)
      Creates a native proxy.
      Parameters:
      nativeHandle - an implementation-specific reference to a native object
      dispose - true if this proxy is responsible to release any resources by calling disposeInternal(); false — otherwise

    • AbstractCloseableNativeProxy

      protected AbstractCloseableNativeProxy​(long nativeHandle, boolean dispose, AbstractCloseableNativeProxy referenced)
      Creates a native proxy.
      Parameters:
      nativeHandle - an implementation-specific reference to a native object
      dispose - true if this proxy is responsible to release any resources by calling disposeInternal(); false — otherwise
      referenced - a referenced native object, that must be alive during the operation of this native proxy

    • AbstractCloseableNativeProxy

      protected AbstractCloseableNativeProxy​(long nativeHandle, boolean dispose, java.util.Collection<AbstractCloseableNativeProxy> referenced)
      Creates a native proxy.
      Parameters:
      nativeHandle - an implementation-specific reference to a native object
      dispose - true if this proxy is responsible to release any resources by calling disposeInternal(); false — otherwise
      referenced - a collection of referenced native objects, that must be alive during the operation of this native proxy

  • Method Details

    • getNativeHandle

      protected final long getNativeHandle()
      Returns a native implementation-specific handle if it may be safely used to access the native object.

      The returned value shall only be passed as an argument to native methods.

      Warning: do not cache the return value, as you won't be able to catch use-after-free.

      Overrides:
      getNativeHandle in class AbstractNativeProxy
      Throws:
      java.lang.IllegalStateException - if this native proxy or any directly or transitively referenced proxies are invalid (closed or nullptr).

    • close

      public final void close()
      Description copied from interface: CloseableNativeProxy
      Closes the native proxy and releases any native resources associated with this proxy.

      Notifies the native code that the native object is no longer needed, and may be safely destroyed. Once closed, the proxy becomes invalid.

      The implementations must be idempotent — do nothing on consecutive invocations.

      Specified by:
      close in interface java.lang.AutoCloseable
      Specified by:
      close in interface CloseableNativeProxy

    • disposeInternal

      protected abstract void disposeInternal()
      Releases any resources owned by this proxy (e.g., the corresponding native object).

      This method is only called once from close() for a valid proxy and shall not be called directly.