Managing local and global references

The Java™ virtual machine tracks the object references that you use in native methods, such as COBOL methods. This tracking ensures that the objects are not prematurely released during garbage collection.

There are two classes of such references:

Local references
Local references are valid only while the method that you invoke runs. Automatic freeing of the local references occurs after the native method returns.
Global references
Global references remain valid until you explicitly delete them. You can create global references from local references by using the JNI service NewGlobalRef.

The following object references are always local:

  • Object references that are received as method parameters
  • Object references that are returned as the method RETURNING value from a method invocation
  • Object references that are returned by a call to a JNI function
  • Object references that you create by using the INVOKE . . . NEW statement

You can pass either a local reference or a global reference as an object reference argument to a JNI service.

You can code methods to return either local or global references as RETURNING values. However, in either case, the reference that is received by the invoking program is a local reference.

You can pass either local or global references as USING arguments in a method invocation. However, in either case, the reference that is received by the invoked method is a local reference.

Local references are valid only in the thread in which you create them. Do not pass them from one thread to another.