It is important to understand the rules determining the life-span of Java object references. These are similar in spirit to the SP_term_refs of the C-Prolog interface, but since they are used to handle Java objects instead of Prolog terms they work a little differently.
Java object references (currently represented in Prolog as
'$java_object'/1 terms) exist in two flavors: local
and global. Their validity are governed by the following rules.
jasper_delete_local_ref/2. It is only valid in the (native) thread in which is was created. As a rule of thumb a local reference can be used safely as long as it is not saved away using
Since local references are never reclaimed until Prolog returns
to Java (which may never happen) you should typically call
jasper_delete_local_ref/2 when your code is done with an object.
Local references can be converted into global references
jasper_create_global_ref/3). When the global reference is no
longer needed, it should be delete using
For a more in-depth discussion of global and local references, consult the JNI Documentation.
Using a local (or global) reference that has been deleted (either explicitly or by returning to Java) is illegal and will generally lead to crashes. This is a limitation of the Java Native Interface used to implement the low level interface to Java.