Package org.graalvm.polyglot

Class PolyglotException

java.lang.Object
java.lang.Throwable
java.lang.Exception
java.lang.RuntimeException
org.graalvm.polyglot.PolyglotException
All Implemented Interfaces:
Serializable
public final class PolyglotException extends RuntimeException
A polyglot exception represents errors that contain Graal guest languages on the stack trace. In addition to the Java stack trace it also returns a polyglot stack trace. Methods like printStackTrace() are implemented such that host and guest language stack traces are printed nicely.

A polyglot exception may have the following properties:

  • Guest Exception: Is true if the exception was raised in guest language code.
  • Host Exception: Is true if this exception was raised in host runtime code. This may happen if the polyglot runtime host runtime methods that throw an exception. The original host exception can be accessed using asHostException().
  • Cancelled: Is true if the execution got cancelled. The execution may be cancelled when closing a context, by a guest language intrinsic or by a tool, like the debugger.
  • Exit: Is true if the execution exited. The guest language triggers exit events if the guest language code request to exit the VM. The exit status can be accessed using getExitStatus().
  • Syntax Error: Is true if the error represents a syntax error. For syntax errors a location may be available.
  • Incomplete Source: Is true if this returns a syntax error that indicates that the source is incomplete.
  • Resource exhausted: Is true if a resource limit e.g. the maximum memory was exhausted.
  • Internal Error: Is true if an internal implementation error occurred in the polyglot runtime, the guest language or an instrument. It is not recommended to show such errors to the user in production. Please consider filing issues for internal implementation errors.
Since:
19.0
See Also:

  • Method Details

    • printStackTrace

      public void printStackTrace()
      Prints host and guest language stack frames to the standard error output.
      Overrides:
      printStackTrace in class Throwable
      Since:
      19.0

    • printStackTrace

      public void printStackTrace(PrintStream s)
      Prints host and guest language stack frames to specified print stream.
      Overrides:
      printStackTrace in class Throwable
      Since:
      19.0

    • printStackTrace

      public void printStackTrace(PrintWriter s)
      Prints host and guest language stack frames to specified print writer.
      Overrides:
      printStackTrace in class Throwable
      Since:
      19.0

    • fillInStackTrace

      public Throwable fillInStackTrace()
      Unsupported, PolyglotException instances are not writable therefore filling the stack trace has no effect for them.
      Overrides:
      fillInStackTrace in class Throwable
      Since:
      19.0

    • getStackTrace

      public StackTraceElement[] getStackTrace()
      Gets stack trace elements for Java and guest languages. For polyglot exceptions it recommended to use getPolyglotStackTrace() as the guest language stack elements do not always fit the Java format for stack trace elements.
      Overrides:
      getStackTrace in class Throwable
      Since:
      19.0

    • getMessage

      public String getMessage()
      Gets a user readable message for the polyglot exception. In case the exception is internal then the original java class name is included in the message. The message never returns null.
      Overrides:
      getMessage in class Throwable
      Since:
      19.0

    • getSourceLocation

      public SourceSection getSourceLocation()
      Gets a guest language source location of this error or null if no source location is available for this exception.
      Since:
      19.0

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
      Since:
      19.0

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Since:
      19.0

    • setStackTrace

      public void setStackTrace(StackTraceElement[] stackTrace)
      Unsupported, PolyglotException instances are not writable therefore setting the stack trace has no effect for them.
      Overrides:
      setStackTrace in class Throwable
      Since:
      19.0

    • getPolyglotStackTrace

      public Iterable<PolyglotException.StackFrame> getPolyglotStackTrace()
      Provides programmatic access to the polyglot stack trace information printed by printStackTrace(). Returns an array of stack trace elements, each representing one stack frame. The zeroth element of the array (assuming the array's length is non-zero) represents the top of the stack, which is the last invocation in the sequence. Typically, this is the point at which this throwable was created and thrown. The last element of the array (assuming the array's length is non-zero) represents the bottom of the stack, which is the first method invocation in the sequence.
      Since:
      19.0
      See Also:

    • isHostException

      public boolean isHostException()
      Returns true if this exception originates from the Java host language. In such a case the first stack frame returns a host frame as zeroth element.
      Since:
      19.0

    • isGuestException

      public boolean isGuestException()
      Returns true if this exception originates from a Graal guest language. In such a case the first stack frame returns a guest frame as zeroth element.
      Since:
      19.0

    • asHostException

      public Throwable asHostException()
      Returns the original Java host exception that caused this exception. The original host exception contains a stack trace that is hardly interpretable by users as it contains details of the language implementation. The polyglot exception provides information for user-friendly error reporting with the polyglot stack trace.
      Throws:
      UnsupportedOperationException - if this exception is not a host exception. Call isHostException() to ensure its originating from the host language.
      Since:
      19.0

    • isInternalError

      public boolean isInternalError()
      Returns true if this exception was caused by an internal implementation error. These errors should be reported as bugs if observed. Internal error messages are typically hard to understand for guest language programmers and might contain implementation specific details that allows guest language implementers to debug the problem.
      Since:
      19.0

    • isResourceExhausted

      public boolean isResourceExhausted()
      Returns true if this exception indicates that a resource limit was exceeded, else false. Resource limit exceeded errors may be raised for the following reasons:
      • The host runtime run out of memory or stack space. For example if host runtime throws OutOfMemoryError or StackOverflowError, then they will be translated to a PolyglotException that return true for isResourceExhausted().
      • A configured resource limit was exceeded.
      • A runtime specific per context resource limit was exceeded. Depending on the host runtime implementation additional options to restrict the resource usage of a context may be specified using options.

      Resource limit exceptions may be originating from the host or guest. Resource limit exceeded errors are never internal, but may have caused the context to be cancelled such that it is no longer usable.

      Since:
      20.2

    • isCancelled

      public boolean isCancelled()
      Returns true if the execution was cancelled. The execution can be cancelled by closing a context, if an instrument such as a debugger decides to cancel the current execution or if a resource limit was exceeded. The context that caused a cancel event becomes unusable, i.e. closed.
      Since:
      19.0

    • isInterrupted

      public boolean isInterrupted()
      Returns true if the current application thread was interrupted by an InterruptedException, or by calling Context.interrupt(Duration) from the host.
      Since:
      20.3

    • isExit

      public boolean isExit()
      Returns true if this exception is caused by an attempt of a guest language program to exit the application. The provided exit code can be accessed using getExitStatus(). This can be the result of either the soft or the hard exit.
      Since:
      19.0
      See Also:

    • isSyntaxError

      public boolean isSyntaxError()
      Returns true if this exception indicates a parser or syntax error. In such a case #get
      Since:
      19.0

    • isIncompleteSource

      public boolean isIncompleteSource()
      Returns true if this exception indicates a syntax error that is indicating that the syntax is incomplete. This allows guest language programmers to find out if more code is expected from a given source. For example, an incomplete JavaScript program could look like this: 
       function incompleteFunction(arg) {
      A shell might react to this exception and prompt for additional source code, if this method returns true.
      Since:
      19.0

    • getGuestObject

      public Value getGuestObject()
      Returns an additional guest language object. Returns null if no exception object is available.
      Since:
      19.0

    • getExitStatus

      public int getExitStatus()
      Returns the exit status if this exception indicates that the application was exited. The exit status is intended to be passed to System.exit(int). In case of hard exit the application can be configured to call System.exit(int) directly using Context.Builder.useSystemExit(boolean).
      Since:
      19.0
      See Also: