All Manuals > LispWorks® User Guide and Reference Manual > 15 Java interface

15.6 Utilities and administration

Use jobject-p to test whether a Lisp object is a jobject or not.

Use lisp-java-instance-p to test whether the argument is an instance of standard-java-object.

get-jobject returns the jobject for a Java object, nil otherwise, and can be used as predicate to determine whether the argument is a valid Java object. Note that if you have an instance of standard-java-object, get-jobject may return nil if the slot is not set. ensure-is-jobject is like get-jobject, but signals an error if its argument is not a jobject.

jobject-class-name can be use to find the Java class raw name of a Java object. jobject-pretty-class-name makes it "pretty", which matches how it appears in the Java code.

jobject-string returns a string representing the object the way Java wants to represent it (the result of Object.toString).

jobject-to-lisp and lisp-to-jobject can be used to convert between Lisp and Java objects of primitive types, which may sometimes be useful.

jvalue is an FLI type descriptor corresponding to the JNI C type jvalue. The functions jvalue-store-jboolean, jvalue-store-jbyte, jvalue-store-jchar, jvalue-store-jshort, jvalue-store-jint, jvalue-store-jlong, jvalue-store-jfloat, jvalue-store-jdouble and jvalue-store-jobject can be used to set values in a jvalue. In typical usage of the Java interface, you will not need to use jvalue at all.

find-java-class can used to find the Java class object for class specification, which normally is the string representing the full class name, but can be also be a keyword for specific primitive types.

jobject-of-class-p can be used to verify whether a Java object is an instance of a class or any of its subclasses.

reset-java-interface-for-new-jvm eliminates cached Java objects from internal Lisp structures. It is intended to be used if you need to start a JVM, stop it and start again. Currently there is no interface to stop the JVM.

intern-and-export-list, default-name-constructor, record-java-class-lisp-symbol, ensure-lisp-classes-from-tree and ensure-supers-contain-java.lang.object are utility functions that are used by the definition generation code, and appear in the output of the importing interface (write-java-class-definitions-to-file, write-java-class-definitions-to-stream and generate-java-class-definitions). Their purpose is to be used by the importing interface, but if you find them useful you can call them directly.

get-superclass-and-interfaces-tree returns a tree of the superclasses and interfaces of a Java class. It is also used internally by the importing interface.

send-message-to-java-host can be used to send a message (a string) to the Java host. This is especially useful when the Lisp is used inside Java, for example on Android, so Java needs to do the displaying of messages to the user.

The variables *to-java-host-stream* and *to-java-host-stream-no-scroll* are output streams that send anything that is written to them to Java (by calling send-message-to-java-host). They can be used anywhere an output stream is needed to make the output go to the Java host.

The Java interface currently may generate at run time specific Java interface conditions of the types below.

Conditions with names ending *-exception are all subclasses of java-exception, and correspond to an exception raised while calling Java. java-exception has two subclasses: java-normal-exception for exceptions that you may get during normal execution, and java-serious-exception, for exceptions that indicate the system is broken in some way. java-serious-exception should never happen, while java-normal-exception may happen in normal code.

The other conditions correspond to errors which are detected inside Lisp.

The java-exception class has three readers, java-exception-string, java-exception-java-backtrace and java-exception-exception-name, which you can use when handling the condition. The macros catching-java-exceptions and catching-exceptions-bind can be used to catch Java exceptions instead of signaling an error. Your code can then access the Java exception directly.

Superclass of the *-error conditions.

Class not found.

Method not found.

Field not found, or was defined with the wrong static-p value.

Setting a field failed, either because it is final or an unacceptable value was supplied.

call-java-method or call-java-static-method failed to find the method.

jobject-call-method failed to find the method.

create-java-object failed to find constructors.

The Java interface detected an error at runtime.

Superclass of all array errors.

Bad index passed to jvref or jaref, or bad start and end passed to other functions accessing arrays.

Trying to store value of wrong type into a Java array.

Superclass of the *-exception conditions.

Superclass of normal exceptions.

Superclass of serious exceptions.

Normal exceptions:

Superclass of field exceptions.

Exception accessing a field (maybe wrong type of value).

Exception inside a call to a Java method.

Serious exceptions:

Failed to find JNI ID for a method.

Failure in some JNI function.

LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:20