Package org.mozilla.jss.util
Class NativeProxy
java.lang.Object
org.mozilla.jss.util.NativeProxy
- All Implemented Interfaces:
AutoCloseable
- Direct Known Subclasses:
BufferProxy
,CertProxy
,CipherContextProxy
,GlobalRefProxy
,KeyProxy
,ModuleProxy
,PRFDProxy
,SigContextProxy
,SocketProxy
,StaticVoidPointer
,TokenProxy
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.
- Version:
- $Revision$ $Date$
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic org.slf4j.Logger
private int
private byte[]
Byte array containing native pointer bytes.private String
String containing backtrace of pointer generation.(package private) static Set
<NativeProxy> Native Proxy Registry(package private) static AtomicInteger
private static final boolean
-
Constructor Summary
ConstructorsModifierConstructorDescriptionNativeProxy
(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 TypeMethodDescriptionstatic void
Assert that the Registry is empty.private static boolean
Internal helper to check whether or not assertions are enabled in the JVM.final void
clear()
Call clear(...) to clear the value of the pointer, setting it to null.final void
close()
Close this NativeProxy by releasing its native resources if they haven't otherwise been freed.boolean
Deep comparison operator.protected void
finalize()
Deprecated.finalize() in Object has been deprecated.int
hashCode()
Hash code based around mPointer value.boolean
isNull()
Whether or not this is a null pointer.static void
Unsafe: Purges all NativeProxies from memory.protected abstract void
Release the native resources used by this proxy.toString()
-
Field Details
-
logger
public static org.slf4j.Logger logger -
saveStacktraces
private static final boolean saveStacktraces -
mPointer
private byte[] mPointerByte array containing native pointer bytes. -
mHashCode
private int mHashCode -
mTrace
String containing backtrace of pointer generation. -
registry
Native Proxy Registry
In debug mode, we keep track of all NativeProxy objects in a static registry. Whenever a NativeProxy is constructed, it registers. Whenever it finalizes, it unregisters. At the end of the game, we should be able to garbage collect and then assert that the registry is empty. This could be done, for example, in the jssjava JVM after main() completes. This registration process verifies that people are calling NativeProxy.finalize() from their subclasses of NativeProxy, so that releaseNativeResources() gets called.
-
registryIndex
-
-
Constructor Details
-
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 Details
-
equals
Deep comparison operator. -
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. -
releaseNativeResources
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:
Exception
-
finalize
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(); } } -
close
Close this NativeProxy by releasing its native resources if they haven't otherwise been freed. See comment in finalize.- Specified by:
close
in interfaceAutoCloseable
- Throws:
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
-
assertsEnabled
private static boolean assertsEnabled()Internal helper to check whether or not assertions are enabled in the JVM. See: https://docs.oracle.com/javase/8/docs/technotes/guides/language/assert.html -
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
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:
Exception
-