Class Root

public class Root
{
  // Methods
  public static int alloc(Object object);
  public static void free(int root);
  public static Object get(int root);
}

This class allows you to create an opaque 32-bit root handle to any Java object. A root handle prevents the contained Java object from being reclaimed by garbage collection, so that the Java object can be safely stored in native data structures. This technique is valuable when using DLL functions that take callback parameters.

For example, when a callback will be used across function calls, you need to protect the Callback object from being reclaimed. You should wrap the Callback inside a root handle and then explicitly free the root handle when you no longer need the Callback.

Suppose you have declared a class called EnumWindowsProc that extends Callback and that will be used across function calls. To protect an instance of this class from garbage collection, you could write the following code.

EnumWindowsProc MyCallback = new EnumWindowsProc;
int rootHandle = Root.alloc(MyCallback); 
// use the Callback across function calls
// until you're done
Root.free(rootHandle);

For more information about declaring and invoking DLL functions that take callbacks, see the Callbacks section of the Microsoft® J/Direct™ article.

Methods

alloc

public static int alloc(Object object);

Creates a new root handle.

Note Root handles require explicit deallocation using the free method. The object will not be reclaimed by the garbage collector until the free method is called.

Return Value:

Returns a new root handle that protects the object from garbage collection.

Parameter	Description
object	The object that the root handle is created for.

free

public static void free(int root);

Releases a root handle.

Return Value:

No return value.

Parameter	Description
root	The handle to release.

get

public static Object get(int root);

Extracts the Java object protected by a root handle.

Return Value:

Returns the Java object protected by the root handle.

Parameter	Description
root	The handle to dereference.