Class Engine.Builder

java.lang.Object
org.graalvm.polyglot.Engine.Builder
Enclosing class:
Engine
public final class Engine.Builder extends Object
Since:
19.0

  • Method Details

    • out

      public Engine.Builder out(OutputStream out)
      Sets the standard output stream to be used for this engine. Every context that uses this engine will inherit the configured output stream if it is not specified in the context. If not set then the system output stream will be used.
      Since:
      19.0

    • err

      public Engine.Builder err(OutputStream err)
      Sets the standard error stream to be used for this engine. Every context that uses this engine will inherit the configured error stream if it is not specified in the context. If not set then the system error stream will be used.
      Since:
      19.0

    • in

      public Engine.Builder in(InputStream in)
      Sets the standard input stream to be used for this engine. Every context that uses this engine will inherit the configured input stream if it is not specified in the context. If not set then the system input stream will be used.
      Since:
      19.0

    • allowExperimentalOptions

      public Engine.Builder allowExperimentalOptions(boolean enabled)
      Allow experimental options to be used for instruments and engine options. Do not use experimental options in production environments. If set to false (the default), then passing an experimental option results in an IllegalArgumentException when the context is built.
      Since:
      19.0

    • useSystemProperties

      public Engine.Builder useSystemProperties(boolean enabled)
      Specifies whether the engine should use system properties if no explicit option is set. The default value is true indicating that the system properties should be used. System properties are looked up with the prefix "polyglot" in order to disambiguate existing system properties. For example, for the option with the key "js.ECMACompatiblity", the system property "polyglot.js.ECMACompatiblity" is read. Invalid options specified using system properties will cause the build method to fail using an IllegalArgumentException. System properties are read once when the engine is built and are never updated after that.
      Parameters:
      enabled - if true system properties will be used as options.
      Since:
      19.0
      See Also:

    • option

      public Engine.Builder option(String key, String value)
      Sets an option for an engine, language or instrument.

      If one of the set option keys or values is invalid then an IllegalArgumentException is thrown when the engine is built. The given key and value must not be null.

      See Engine.getOptions() to list all available options for engines.

      See Language.getOptions() to list all available options for a language.

      See Instrument.getOptions() to list all available options for an instrument.

      Since:
      19.0

    • sandbox

      public Engine.Builder sandbox(SandboxPolicy policy)
      Sets a code sandbox policy to an engine. By default, the engine's sandbox policy is SandboxPolicy.TRUSTED, there are no restrictions to the engine configuration.
      Since:
      23.0
      See Also:

    • options

      public Engine.Builder options(Map<String,String> options)
      Shortcut for setting multiple options using a map. All values of the provided map must be non-null.
      Parameters:
      options - a map options.
      Since:
      19.0
      See Also:

    • serverTransport

      public Engine.Builder serverTransport(MessageTransport serverTransport)
      Take over transport of message communication with a server peer. Provide an implementation of MessageTransport to virtualize a transport of messages to a server endpoint. MessageTransport.open(java.net.URI, org.graalvm.polyglot.io.MessageEndpoint) corresponds to accept of a server socket.
      Parameters:
      serverTransport - an implementation of message transport interceptor
      Since:
      19.0
      See Also:

    • exceptionHandler

      public Engine.Builder exceptionHandler(Consumer<PolyglotException> handler)
      Sets an exception handler that is invoked whenever a PolyglotException is about to be thrown from a engine bound value back to the host. The configured custom exception handler gets inherited by all contexts created with this engine.

      The handler is called on the host thread that performs the polyglot operation, for example when invoking Value methods, executing guest code, or initializing a language. It receives the PolyglotException that would normally be thrown to the caller.

      The handler can inspect the exception, perform additional logging or metrics, or translate the PolyglotException into a different exception type. If the handler throws an exception, that exception is propagated to the caller instead of the original PolyglotException. If the handler returns normally, the original PolyglotException is thrown as usual.

      A common use case is to unwrap and rethrow host runtime exceptions so that calling code can handle them directly: 

      static void rethrowHostRuntimeException(PolyglotException e) {
    if (e.isHostException()) {
        Throwable t = e.asHostException();
        if (t instanceof RuntimeException rt) {
            // rethrow the original host runtime exception
            throw rt;
        }
    }
    // fall through, the PolyglotException will be thrown
}

try (Context c = Context.newBuilder()
                .exceptionHandler(MyHost::rethrowHostRuntimeException)
                .build()) {
    try {
        // Without an exception handler, this would throw a PolyglotException
        // wrapping the IllegalStateException as a host exception.
        c.asValue(new IllegalStateException("test")).throwException();
    } catch (IllegalStateException e) {
        // The handler rethrew the original host exception.
        assert "test".equals(e.getMessage());
    }
}
      In this example, Value.throwException() would normally throw a PolyglotException. Because the handler rethrows the underlying host RuntimeException, the caller observes IllegalStateException directly instead of PolyglotException.

      Handlers should be written carefully, because any host call into the context can then appear to throw additional exception types. In particular, translating guest exceptions into unrelated runtime exceptions can make APIs harder to reason about and should only be done with care.

      Parameters:
      handler - the handler to invoke before a PolyglotException is thrown to the host, or null to disable custom handling
      Since:
      25.1
      See Also:

    • logHandler

      public Engine.Builder logHandler(Handler logHandler)
      Installs a new logging Handler. The logger's Level configuration is done using the Engine's options. The level option key has the following format: log.languageId.loggerName.level or log.instrumentId.loggerName.level. The value is either the name of pre-defined Level constant or a numeric Level value. If not explicitly set in options the level is inherited from the parent logger.

      Examples of setting log level options:
      builder.option("log.level","FINE"); sets the FINE level to all TruffleLoggers.
      builder.option("log.js.level","FINE"); sets the FINE level to JavaScript TruffleLoggers.
      builder.option("log.js.com.oracle.truffle.js.parser.JavaScriptLanguage.level","FINE"); sets the FINE level to TruffleLogger for the JavaScriptLanguage class.

      Parameters:
      logHandler - the Handler to use for logging in engine's Contexts. The passed logHandler is closed when the engine is closed.
      Returns:
      the Engine.Builder
      Since:
      19.0

    • logHandler

      public Engine.Builder logHandler(OutputStream logOut)
      Installs a new logging Handler using given OutputStream. The logger's Level configuration is done using the Engine's options. The level option key has the following format: log.languageId.loggerName.level or log.instrumentId.loggerName.level. The value is either the name of pre-defined Level constant or a numeric Level value. If not explicitly set in options the level is inherited from the parent logger.

      Examples of setting log level options:
      builder.option("log.level","FINE"); sets the FINE level to all TruffleLoggers.
      builder.option("log.js.level","FINE"); sets the FINE level to JavaScript TruffleLoggers.
      builder.option("log.js.com.oracle.truffle.js.parser.JavaScriptLanguage.level","FINE"); sets the FINE level to TruffleLogger for the JavaScriptLanguage class.

      Parameters:
      logOut - the OutputStream to use for logging in engine's Contexts. The passed logOut stream is closed when the engine is closed.
      Returns:
      the Engine.Builder
      Since:
      19.0

    • build

      public Engine build()
      Creates a new engine instance from the configuration provided in the builder. The same engine builder can be used to create multiple engine instances.
      Since:
      19.0