Next: Handling Java Exceptions, Previous: Conversion between Prolog Arguments and Java Types, Up: The Jasper Library [Contents][Index]
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
assert/3
or similar.
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 deleted using
jasper_delete_global_ref/2
.
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.