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:

  • Method Details

    • throwUsingJNI

      public void throwUsingJNI(org.graalvm.jniutils.JNI.JNIEnv env)
      Re-throws this exception in host 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

    • getJNICalls

      public static org.graalvm.jniutils.JNICalls getJNICalls()
      Returns the JNICalls 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.