jasper_initialize(-JVM)jasper_initialize(+Options, -JVM)Loads and initializes the Java VM. JVM is a reference to the Java VM. Options is a list of options. The options can be of the following types:
classpath(<classpath>)If <classpath> is an atom, then it will be added (unmodified) to
the Java VM’s classpath. If <classpath> is a list, then each
element will be expanded using absolute_file_name/2 and
concatenated using the Java VM’s path-separator. Example:
classpath([library('jasper/examples'),'$HOME/joe'])
In addition to the classpaths specified here, Jasper will automatically
add jasper.jar to the classpath together with the contents of the
CLASSPATH environment variable.
if_exists(option)This option determines what happens if a JVM has already been initialized,
either through a previous call to jasper_initialize or because
Prolog have been called from Java. If a JVM already exists, then the
other options are ignored.
okThe default. Argument JVM is bound to the existing JVM.
failThe call to jasper_initialize/2 fails.
errorThe call to jasper_initialize/2 throws an exception
(java_exception(some text)).
if_not_exists(option)This option determines what happens if a JVM has not already been initialized.
okThe default. The remaining options are used to initialize the JVM.
failThe call to jasper_initialize/2 fails.
errorThe call to jasper_initialize/2 throws an exception
(java_exception(some text)).
As an example, to access the currently running JVM and to give an error
if there is no running JVM use
jasper_initialize([if_exists(ok),if_not_exists(error)], JVM).
OptionThe option is an atom that will be passed directly to the Java VM as an option. This enables the user to send additional options to the Java VM. Example:
jasper_initialize(['-Dkenny.is.dead=42'],JVM),
In addition to the options specified by the user, Jasper adds a couple of options on its own in order for Java to find the Jasper classes and the Jasper native library.
There is currently no support for creating multiple JVMs (few JDKs, if any, supports this).
jasper_deinitialize(+JVM)De-initialize Java. Do Not call this, current versions of the JVM does not support deinitialization.
jasper_call(+JVM,+Method,+TypeInfo,+Args)Calls a Java static or instance method.
A reference to the Java VM, as obtained by
jasper_initialize/[1,2].
A term of the form method(ClassName,
MethodName, Flags) that identifies the method to call.
This is the Fully Qualified Classname of the class (for example,
java/lang/String) of the object or where to look for the static
method. Note that you need to surround the atom with single
quotes since it contains / characters. The class is ignored when
calling instance methods but should still be an atom, e.g.
''.
This is the name of the method, as an atom.
This is the singleton list [instance] for
instance methods and [static] for static methods.
Information about the argument types and the argument conversion that should be applied. See Conversion between Prolog Arguments and Java Types for more information on specifying argument types.
Note that for an instance method the first argument must be an
object reference (specified with +object(Class)). In this
case the class is ignored but should still be an atom, e.g.
''.
A term with one position for each argument to the method. For an instance method the first argument is the instance.
jasper_new_object(+JVM,+ClassName,+TypeInfo,+Args,-Object)Creates a new Java object.
See jasper_call/4 above for an explanation of the arguments
JVM, ClassName, TypeInfo and Args.
An an atom containing the fully qualified classname
TypeInfo has the same format as for a static void method.
A term with one position for each argument to the constructor.
This argument is bound to a (local) reference to the created object. See Global vs. Local References.
As an example, the following code creates a
java/lang/Integer object initialized from a string of digits. It
then calls the instance method doubleValue to obtain the floating
point representation of the Integer.
| ?- Chars = "4711",
%% get existing JVM
jasper_initialize([if_not_exists(error)], JVM),
jasper_new_object(JVM, 'java/lang/Integer',
init(+chars), init(Chars), S),
jasper_call(JVM,
method('java/lang/Integer', doubleValue, [instance]),
to_double(+object('java/lang/Integer'), [-double]),
to_double(S,X)).
S = '$java_object'(135875344),
X = 4711.0, % note that this is now a floating point number
JVM = '$jvm'(1076414148),
Chars = [52,55,49,49] % a.k.a. "4711"
jasper_create_global_ref(+JVM,+Ref,-GlobalRef)Creates a global reference (GlobalRef) for a (non-null) Java object (Ref). See Global vs. Local References.
jasper_delete_global_ref(+JVM,+GlobalRef)Destroys a global reference. See Global vs. Local References.
jasper_create_local_ref(+JVM,+Ref,-LocalRef)Creates a local reference (LocalRef) for a (non-null) Java object (Ref). See Global vs. Local References. Rarely needed.
jasper_delete_local_ref(+JVM,+GlobalRef)Destroys a local reference. See Global vs. Local References.
jasper_is_jvm(+JVM)Succeeds if JVM is a reference to a Java Virtual Machine.
jasper_is_object(+Object)jasper_is_object(+JVM,+Object)Succeeds if Object is a reference to a Java object. The
representation of Java object will change so use
jasper_is_object/1 to recognize objects instead of relying on the
internal representation. Currently the JVM argument is
ignored. If, and when, multiple JVMs becomes a possibility
jasper_is_object/2 will verify that Object is an object in
a particular JVM.
jasper_is_same_object(+JVM,+Object1,+Object2)Succeeds if Object1 and Object2 refers to the same Java
object (or both are null object references). The same object may be
represented by two different terms in Prolog so ==/2 can
not be used to reliably detect if two object references refer to
the same object.
jasper_is_instance_of(+JVM,+Object,+ClassName)Succeeds if Object is an instance of class ClassName;
fails otherwise. ClassName is a fully qualified classname; see
jasper_call/4.
jasper_object_class_name(+JVM,+Object,-ClassName)Returns the fully qualified name of the class of +Object as an atom.
jasper_null(+JVM,-NullRef)Create a null object reference.
jasper_is_null(+JVM,+Ref)Succeeds if Ref is a null object reference, fails otherwise, e.g. if Ref is not an object reference.