catching-java-exceptions

catching-exceptions-bind Macros

Summary

Execute Lisp code with a catch for Java exceptions.

Package

lw-ji

Signatures

catching-java-exceptions &body body

catching-exceptions-bind (result exception) form &body body

Arguments

body⇩	Lisp code.
result⇩	A variable.
exception⇩	A variable.
form⇩	A Lisp form.

Description

The macro catching-java-exceptions executes body with a catch for Java exceptions. The code of body is executed normally, and if no Java exception is signaled through the execution, returns whatever body returns. If there is an exception, instead of signaling an error of class java-exception, catching-java-exceptions returns two values: nil and the Java exception object (analogous to cl:ignore-errors).

The macro catching-exceptions-bind executes form and binds result and exception to the first two return values if there was no exception. If there was an exception they are bound to nil and the exception. It then executes the code of body within the scope of the bind. catching-exceptions-bind is equivalent to:

(multiple-value-bind (result exception)
  (catching-java-exceptions form)
      body)

Notes

1. jobject-string, jobject-class-name and jobject-of-class-p are useful general utilities for deciding what to do with the exception. For find-grained handling, you will need to access the exception using your own callers or call-java-method when applicable.
2. These macros have no effect on signaling and handling of other errors in Lisp, except that they prevent Java exceptions from being signaled as errors.
3. Some exceptions can happen during normal execution and handled by the system in a user-invisible way (analogous to the way that try in Java code does). These macros do not affect the behavior for these cases, so even though when running under a Java debugger you may see an exception, it will not necessarily be visible with these macros.
4. In general, these macros are less useful in high-level code, because they cause exceptions to throw out, preventing them from being signaled as Lisp errors and handled by error handler in the scope of body (for catching-java-exceptions) or form (for catching-exceptions-bind). They should normally be used in low-level code that actually does Java calls, with any Lisp error handlers wrapped around them.
5. For simple handling of exceptions you can use standard handlers (cl:handler-case, cl:handler-bind), for java-exception and its subclasses.

See also

jobject-string
jobject-class-name
jobject-of-class-p