com.exonum.binding.proxy

Class AbstractCloseableNativeProxy

java.lang.Object

com.exonum.binding.proxy.AbstractNativeProxy

com.exonum.binding.proxy.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.

Field Summary

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

nativeHandle

Constructor Summary

Constructors

Modifier	Constructor and 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 and 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.proxy.AbstractNativeProxy

isValidHandle

Methods inherited from class java.lang.Object

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

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 CloseableNativeProxy

Specified by:

close in interface java.lang.AutoCloseable

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.