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

public abstract class NativeProxy extends Object implements 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.
Version:
$Revision$ $Date$
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static 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

    Constructors
    Modifier
    Constructor
    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
    Description
    static 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
    Call clear(...) to clear the value of the pointer, setting it to null.
    final void
    Close this NativeProxy by releasing its native resources if they haven't otherwise been freed.
    boolean
    Deep comparison operator.
    protected void
    Deprecated.
    finalize() in Object has been deprecated.
    int
    Hash code based around mPointer value.
    boolean
    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.
     

    Methods inherited from class java.lang.Object

    clone, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • logger

      public static org.slf4j.Logger logger
    • saveStacktraces

      private static final boolean saveStacktraces
    • mPointer

      private byte[] mPointer
      Byte array containing native pointer bytes.
    • mHashCode

      private int mHashCode
    • mTrace

      private String mTrace
      String containing backtrace of pointer generation.
    • registry

      static Set<NativeProxy> 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

      static AtomicInteger 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

      public boolean equals(Object obj)
      Deep comparison operator.
      Overrides:
      equals in class 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 Object
    • releaseNativeResources

      protected abstract void releaseNativeResources() throws 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:
      Exception
    • finalize

      @Deprecated protected void finalize() throws 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 Object
      Throws:
      Throwable
    • close

      public final void close() throws 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 AutoCloseable
      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

      public String toString()
      Overrides:
      toString in class Object
    • 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

      public static void purgeAllInRegistry() throws 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:
      Exception