ej.sni

Class NativeResource

java.lang.Object

ej.sni.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 Summary

Modifier and Type	Method and Description
static Object	clearCloseOnGC(long resource, long closeFunction) Cancels an automatic close configuration done previously with closeOnGC(long, long, Object).
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.
String	getDescription() Returns a string describing this resource.
long	getId() Returns the integer value of the resource pointer given to SNI_registerResource().
static NativeResource	getNativeResource(long resource, long closeFunction) Returns the native resource registered with the given resource and closeFunction pair.
Object	getOwner() Returns an object representing the owner of the resource.
static int	getRegisteredNativeResourcesCount() Returns the number of registered native resources.
static Iterable<NativeResource>	listRegisteredNativeResources() Returns an object to iterate over the registered native resources.
static void	printRegisteredNativeResources(PrintStream out) Prints a description of the registered native resources to the specified print stream.

Methods inherited from class java.lang.Object

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

Method Detail

getOwner

public Object getOwner()

Returns an object representing the owner of the resource.

getId

public long getId()

Returns the integer value of the resource pointer given to SNI_registerResource().

getDescription

public String getDescription()

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

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()

Returns an object to iterate over the 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()

Returns the number of registered native resources.

getNativeResource

public static NativeResource getNativeResource(long resource,
                                               long closeFunction)

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