jcheck: Java exception handling

Description

.jcheck checks the Java VM for any pending exceptions and clears them.

.jthrow throws a Java exception.

.jgetEx polls for any pending exceptions and returns the exception object.

.jclear clears a pending exception.

Usage

.jcheck(silent = FALSE)
.jthrow(exception, message = NULL)
.jgetEx(clear = FALSE)
.jclear()

Value

.jcheck returns TRUE if an exception occurred or

FALSE otherwise.

.jgetEx returns NULL if there are no pending exceptions or an object of the class "java.lang.Throwable" representing the current exception.

Arguments

silent: If set to FALSE then Java is instructed to print the exception on stderr. Note that Windows Rgui doesn't show stderr so it will not appear there (as of rJava 0.5-1 some errors that the JVM prints using the vfprintf callback are passed to R. However, some parts are printed using System.err in which case the usual redirection using the System class can be used by the user).
exception: is either a class name of an exception to create or a throwable object reference that is to be thrown.
message: if exception is a class name then this parameter specifies the string to be used as the message of the exception. This parameter is ignored if exception is a reference.
clear: if set to TRUE then the returned exception is also cleared, otherwise the throwable is returned without clearing the cause.

Details

Please note that some functions (such as .jnew or .jcall) call .jcheck implicitly unless instructed to not do so. If you want to handle Java exceptions, you should make sure that those function don't clear the exception you may want to catch.

The exception handling is still as a very low-level and experimental, because it requires polling of exceptions. A more elaborate system using constructs similar to try ... catch is planned for next major version of rJava.

Warning: When requesting exceptions to not be cleared automatically, please note that the show method (which is called by print) has a side-effect of making a Java call to get the string representation of a Java object. This implies that it will be impeded by any pending exceptions. Therefore exceptions obtained through .jgetEx can be stored, but should not be printed (or otherwise used in Java calls) until after the exception is cleared. In general, all Java calls will fail (possibly silently) until the exception is cleared.

Examples

Run this code

# \donttest{
# we try to create a bogus object and
# instruct .jnew to not clear the exception
# this will raise an exception
v <- .jnew("foo/bar", check=FALSE)

# you can poll for the exception, but don't try to print it
# (see details above)
if (!is.null(e<-.jgetEx())) print("Java exception was raised")

# expect TRUE result here because the exception was still not cleared
print(.jcheck(silent=TRUE))
# next invocation will be FALSE because the exception is now cleared
print(.jcheck(silent=TRUE))

# now you can print the actual expection (even after it was cleared)
print(e)
# }