Package com.exonum.binding.proxy

Class AbstractCloseableNativeProxy

  • All Implemented Interfaces:
    CloseableNativeProxy, java.lang.AutoCloseable
    Direct Known Subclasses:
    MemoryDb, NodeProxy
    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.

    • Constructor Detail

      • 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 Detail

      • 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.