com.entrust.toolkit.capi

Class CapiHandle

java.lang.Object

com.entrust.toolkit.capi.CapiHandle

Direct Known Subclasses:

CertChainContext, CertContext, CertStore, CryptHash, CryptKey, CryptProvider

public abstract class CapiHandle
extends java.lang.Object

This class represents a handle to an object in Microsoft's CAPI. It acts as the base class for all native types for which a handle or pointer is allocated and returned.

It is very important that the close method be called after the object is no longer needed to free memory allocated by native code. Not calling close can result in memory leaks, and possibly even crash the Java VM.

Most toolkit users will not need to use this class directly.

Since:

7.0

Method Summary

Methods

Modifier and Type	Method and Description
protected void	clearHandle() Clears the handle without freeing memory.
abstract void	close() Close the handle, releasing the memory allocated by CAPI functions.
static void	debugInfo() Writes information about current handle allocation to System.out.
static void	debugInfo(boolean showAllocation) Writes information about current handle allocation to System.out.
boolean	equals(java.lang.Object anotherHandle) Equals method, for debugging purposes.
protected void	finalize() Attempts to release the handle owned by this object.
protected long	getHandle() Returns the actual handle represented by this object.
int	hashCode() hashCode method, for debugging purposes.
static void	setExtendedDebugging(boolean extendedDebugging) Turn on or off extended debugging information.

Methods inherited from class java.lang.Object

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

Method Detail

debugInfo

public static void debugInfo()

Writes information about current handle allocation to System.out. This method is useful for debugging memory allocation and making sure resources allocated in native code are being correctly released.

This method is not guaranteed to remain in future toolkit versions, it should be used in debug code only.

debugInfo

public static void debugInfo(boolean showAllocation)

Writes information about current handle allocation to System.out. This method is useful for debugging memory allocation and making sure resources allocated in native code are being correctly released.

This method is not guaranteed to remain in future toolkit versions, it should be used in debug code only.

Parameters:

showAllocation - Show where handles were allocated, if the information is available.

setExtendedDebugging

public static void setExtendedDebugging(boolean extendedDebugging)

Turn on or off extended debugging information.

This method is not guaranteed to remain in future toolkit versions, it should be used in debug code only.

Parameters:

extendedDebugging -

close

public abstract void close()

Close the handle, releasing the memory allocated by CAPI functions. After this call, the handle cannot be used for any more native calls.

It is okay to call this method multiple times on the same object.

getHandle

protected long getHandle()

Returns the actual handle represented by this object.

Returns:

the actual handle represented by this object.

clearHandle

protected void clearHandle()

Clears the handle without freeing memory. Useful after native calls that implicitly close a handle, such as CertEnumCertificatesInStore.

equals

public boolean equals(java.lang.Object anotherHandle)

Equals method, for debugging purposes.

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

hashCode method, for debugging purposes.

Overrides:

hashCode in class java.lang.Object

finalize

protected void finalize()
                 throws java.lang.Throwable

Attempts to release the handle owned by this object. This mechanism should not be relied upon, programs should explicitly call the close method when a handle is no longer required. This method is a "last resort" to attempt to prevent memory leaks.

Overrides:

finalize in class java.lang.Object

Throws:

java.lang.Throwable