SICStus Prolog

Jasper Library Predicates

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 it will be added (unmodified) to the Java VM's classpath. If <classpath> is a list, 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.

ok: The default. Argument JVM is bound to the existing JVM.
fail: The call to jasper_initialize/2 fails.
error: The 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.

ok: The default. The remaining options are used to initialize the JVM.
fail: The call to jasper_initialize/2 fails.
error: The 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).

Option

The 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.

JVM

A reference to the Java VM, as obtained by jasper_initialize/[1,2].

TypeInfo

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. ''.

Args

A term with one position for each argument to the constructor.

Method

A term of the form method(ClassName,MethodName, Flags) that identifies the method to call.

ClassName: 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. ''.
Name: This is the name of the method, as an atom.
Flags: This is the singleton list [instance] for instance methods and [static] for static methods.

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.

ClassName: An an atom containing the fully qualified classname
TypeInfo: TypeInfo has the same format as for a static void method.
Args: A term with one position for each argument to the constructor.
Object: 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.