Package ej.sni

Class NativeResource

  • public final class NativeResource
extends Object
    A NativeResource is an object representing a runtime element managed by the native side (such as a file, a socket, an image, ...).

    A NativeResource is registered using the C function SNI_registerResource() and unregistered using the C function SNI_unregisterResource(). NativeResource can be listed using the listRegisteredNativeResources() method.

    • Method Detail

      • getOwner

        public Object getOwner()
        Gets an object representing the owner of the resource.
        Returns:
        an object representing the owner of the resource.

      • getId

        public long getId()
        Gets the integer value of the resource pointer given to SNI_registerResource().
        Returns:
        the integer value of the resource pointer given to SNI_registerResource().

      • getDescription

        public String getDescription()
        Gets a string describing this resource.
        Returns:
        a string describing this resource.

      • closeOnGC

        public static void closeOnGC​(long resource,
                             long closeFunction,
                             Object obj)
        Registers the given native resource to be closed automatically when the given object is garbage collected.

        The native resource is identified by the pair resource, closeFunction.

        The native resource must have been registered previously in C using the SNI function SNI_registerResource(). If later the native resource is explicitly closed using the SNI function SNI_unregisterResource() then the automatic close configuration is cancelled.

        At most one object can be registered for the given native resource. The same object can be registered for several native resources.

        Parameters:
        resource - the resource argument given to SNI_registerResource() when the native resource has been registered.
        closeFunction - the close argument given to SNI_registerResource() when the native resource has been registered.
        obj - when this object is garbage collected, the native resource is closed.
        Throws:
        IllegalArgumentException - if the given native resource is not registered or if closeOnGC(long, long, Object) has already been called for the given native resource.
        NullPointerException - if obj is null.

      • clearCloseOnGC

        @Nullable
public static Object clearCloseOnGC​(long resource,
                                    long closeFunction)
        Cancels an automatic close configuration done previously with closeOnGC(long, long, Object).

        This method doesn't need to be called if the native resource will be closed using the SNI function SNI_unregisterResource().

        Parameters:
        resource - the resource argument given to closeOnGC(long, long, Object).
        closeFunction - the closeFunction argument given to closeOnGC(long, long, Object).
        Returns:
        the object that has been passed to closeOnGC(long, long, Object) or null if no automatic close is configured for the given native resource or if the object has been garbage collected.
        Throws:
        IllegalArgumentException - if the given native resource is not registered or has already been closed.

      • listRegisteredNativeResources

        public static Iterable<NativeResource> listRegisteredNativeResources()
        Gets the list of registered native resources.

        A native resources is registered using the C function SNI_registerResource().

        Returns:
        an Iterable of registered NativeResource objects.

      • printRegisteredNativeResources

        public static void printRegisteredNativeResources​(PrintStream out)
        Prints a description of the registered native resources to the specified print stream.

        A native resources is registered using the C function SNI_registerResource().

        Parameters:
        out - PrintStream to use for output.

      • getRegisteredNativeResourcesCount

        public static int getRegisteredNativeResourcesCount()
        Gets the number of registered native resources.
        Returns:
        the number of registered native resources.

      • getNativeResource

        @Nullable
public static NativeResource getNativeResource​(long resource,
                                               long closeFunction)
        Gets the native resource registered with the given resource and closeFunction pair.

        Parameters:
        resource - the resource argument given to SNI_registerResource() when the native resource has been registered.
        closeFunction - the close argument given to SNI_registerResource() when the native resource has been registered.
        Returns:
        a NativeResource or null if no NativeResource has been registered for the given resource and closeFunction pair.