org.graalvm.nativebridge

Class ForeignException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.graalvm.nativebridge.ForeignException

All Implemented Interfaces:

Serializable

public final class ForeignException
extends RuntimeException

This exception is used to transfer a local exception over the boundary. The local exception is marshaled, passed over the boundary as a ForeignException, unmarshalled, and re-thrown.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
static ForeignException	forThrowable(Throwable exception, BinaryMarshaller<? super Throwable> marshaller) Creates a ForeignException by marshaling the exception using marshaller.
static HotSpotCalls	getHotSpotCalls() Returns the HotSpotCalls transferring the ForeignException thrown in the HotSpot to an isolate.
static StackTraceElement[]	mergeStackTrace(StackTraceElement[] foreignExceptionStack) Merges foreign stack trace marshalled in the ForeignException with local ForeignException's stack trace.
void	throwInHotSpot(JNI.JNIEnv env) Re-throws this exception in HotSpot using a JNI API.
RuntimeException	throwOriginalException(BinaryMarshaller<? extends Throwable> marshaller) Unmarshalls the foreign exception transferred by this ForeignException and re-throws it.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Method Detail

throwInHotSpot

public void throwInHotSpot(JNI.JNIEnv env)

Re-throws this exception in HotSpot using a JNI API. This method is intended to be called by the code generated by the bridge processor. It's still possible to use it by the hand-written code, but it's recommended to use the bridge processor.

throwOriginalException

public RuntimeException throwOriginalException(BinaryMarshaller<? extends Throwable> marshaller)

Unmarshalls the foreign exception transferred by this ForeignException and re-throws it. This method is intended to be called by the code generated by the bridge processor. It's still possible to use it by the hand-written code, but it's recommended to use the bridge processor.

Parameters:

marshaller - the marshaller to unmarshal the exception

mergeStackTrace

public static StackTraceElement[] mergeStackTrace(StackTraceElement[] foreignExceptionStack)

Merges foreign stack trace marshalled in the ForeignException with local ForeignException's stack trace. This is a helper method for throwable marshallers to merge local and foreign stack traces. Typical usage looks like this:

 final class DefaultThrowableMarshaller implements BinaryMarshaller<Throwable> {
     private final BinaryMarshaller<StackTraceElement[]> stackTraceMarshaller = MyJNIConfig.getDefault().lookupMarshaller(StackTraceElement[].class);

     @Override
     public Throwable read(BinaryInput in) {
         String foreignExceptionClassName = in.readUTF();
         String foreignExceptionMessage = in.readUTF();
         StackTraceElement[] foreignExceptionStack = stackTraceMarshaller.read(in);
         RuntimeException exception = new RuntimeException(foreignExceptionClassName + ": " + foreignExceptionMessage);
         exception.setStackTrace(ForeignException.mergeStackTrace(foreignExceptionStack));
         return exception;
     }

     @Override
     public void write(BinaryOutput out, Throwable object) {
         out.writeUTF(object.getClass().getName());
         out.writeUTF(object.getMessage());
         stackTraceMarshaller.write(out, object.getStackTrace());
     }
 }
 

Parameters:

foreignExceptionStack - the stack trace marshalled into the ForeignException

Returns:

the stack trace combining both local and foreign stack trace elements

forThrowable

public static ForeignException forThrowable(Throwable exception,
                                            BinaryMarshaller<? super Throwable> marshaller)

Creates a ForeignException by marshaling the exception using marshaller. This method is intended to be called by the code generated by the bridge processor. It's still possible to use it by the hand-written code, but it's recommended to use the bridge processor.

Parameters:

exception - the exception that should be passed over the boundary

marshaller - the marshaller to marshall the exception

getHotSpotCalls

public static HotSpotCalls getHotSpotCalls()

Returns the HotSpotCalls transferring the ForeignException thrown in the HotSpot to an isolate. This method is intended to be called by the code generated by the bridge processor. It's still possible to use it by the hand-written code, but it's recommended to use the bridge processor.