org.mozilla.jss.util

Class NativeProxy

java.lang.Object

org.mozilla.jss.util.NativeProxy

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

BufferProxy, GlobalRefProxy, PRFDProxy, StaticVoidPointer, TokenProxy

public abstract class NativeProxy
extends java.lang.Object
implements java.lang.AutoCloseable

NativeProxy, a superclass for Java classes that mirror C data structures. It contains some code to help make sure that native memory is getting freed properly.

Field Summary

Fields

Modifier and Type	Field and Description
static org.slf4j.Logger	logger

Constructor Summary

Constructors

Modifier	Constructor and Description
	NativeProxy(byte[] pointer) Create a NativeProxy from a byte array representing a C pointer.
protected	NativeProxy(byte[] pointer, boolean track) Create a NativeProxy from a byte array representing a C pointer.

Method Summary

Modifier and Type	Method and Description
static void	assertRegistryEmpty() Assert that the Registry is empty.
void	clear() Call clear(...) to clear the value of the pointer, setting it to null.
void	close() Close this NativeProxy by releasing its native resources if they haven't otherwise been freed.
boolean	equals(java.lang.Object obj) Deep comparison operator.
protected void	finalize() Deprecated. finalize() in Object has been deprecated. Use close(...) from the AutoCloseable interface instead.
int	hashCode() Hash code based around mPointer value.
boolean	isNull() Whether or not this is a null pointer.
static void	purgeAllInRegistry() Unsafe: Purges all NativeProxies from memory.
protected abstract void	releaseNativeResources() Release the native resources used by this proxy.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, wait, wait, wait

Field Detail

logger

public static org.slf4j.Logger logger

Constructor Detail

NativeProxy

public NativeProxy(byte[] pointer)

Create a NativeProxy from a byte array representing a C pointer. This is the primary way of creating a NativeProxy; it should be called from the constructor of your subclass.

Parameters:

pointer - A byte array, created with JSS_ptrToByteArray, that contains a pointer pointing to a native data structure. The NativeProxy instance acts as a proxy for that native data structure.

NativeProxy

protected NativeProxy(byte[] pointer,
                      boolean track)

Create a NativeProxy from a byte array representing a C pointer. This allows for creating an untracked NativeProxy instance (when track=false), which allows for creating NativeProxy instances out of stack-allocated variables and/or creating NativeProxies which aren't freed.

Method Detail

equals

public boolean equals(java.lang.Object obj)

Deep comparison operator.

Overrides:

equals in class java.lang.Object

Returns:

true if obj has the same underlying native pointer. false if the obj is null or has a different underlying native pointer.

hashCode

public int hashCode()

Hash code based around mPointer value. Note that Object.hashCode() isn't sufficient as it tries to determine the Object's value based on all internal variables. Because we want a single static hashCode that is unique to each instance of nativeProxy, we construct it up front based on an incrementing counter and cache it throughout the lifetime of this object.

Overrides:

hashCode in class java.lang.Object

releaseNativeResources

protected abstract void releaseNativeResources()
                                        throws java.lang.Exception

Release the native resources used by this proxy. Subclasses of NativeProxy must define this method to clean up data structures in C code that are referenced by this proxy. releaseNativeResources() will usually be implemented as a native method.

You don't call this method; NativeProxy.finalize() or close() calls it for you.

If you free these resources explicitly, call clear(); instead.

Throws:

java.lang.Exception

finalize

@Deprecated
protected void finalize()
                             throws java.lang.Throwable

Deprecated. finalize() in Object has been deprecated. Use close(...) from the AutoCloseable interface instead.

Finalize this NativeProxy by releasing its native resources. The finalizer calls releaseNativeResources() so you don't have to. This finalizer should be called from the finalize() method of all subclasses: class MyProxy extends NativeProxy { [...] protected void finalize() throws Throwable { // do any object-specific finalization other than // releasing native resources [...] super.finalize(); } }

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable

close

public final void close()
                 throws java.lang.Exception

Close this NativeProxy by releasing its native resources if they haven't otherwise been freed. See comment in finalize.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception

clear

public final void clear()

Call clear(...) to clear the value of the pointer, setting it to null. This should be used when the pointer has been freed by another means. Similar to finalize(...) or close(...), except that it doesn't call releaseNativeResources(...). See also: JSS_clearPtrFromProxy(...) in jssutil.h

isNull

public boolean isNull()

Whether or not this is a null pointer.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

assertRegistryEmpty

public static void assertRegistryEmpty()

Assert that the Registry is empty. Only works in debug mode; in ship mode, it is a no-op. If the Registry is not empty when this is called, an assertion (org.mozilla.jss.util.AssertionException) is thrown.

purgeAllInRegistry

public static void purgeAllInRegistry()
                               throws java.lang.Exception

Unsafe: Purges all NativeProxies from memory. In the rare instances where we wish to shutdown an existing CryptoManager, all native proxies need to be cleared and freed. This will result in any lingering references to stop working, but should ensure that an application can recover from this scenario.

Throws:

java.lang.Exception