org.graalvm.polyglot

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 Summary

Modifier and Type	Method and Description
Engine.Builder	allowExperimentalOptions(boolean enabled) Allow experimental options to be used for instruments and engine options.
Engine	build() Creates a new engine instance from the configuration provided in the builder.
Engine.Builder	err(OutputStream err) Sets the standard error stream to be used for this engine.
Engine.Builder	in(InputStream in) Sets the standard input stream to be used for this engine.
Engine.Builder	logHandler(Handler logHandler) Installs a new logging Handler.
Engine.Builder	logHandler(OutputStream logOut) Installs a new logging Handler using given OutputStream.
Engine.Builder	option(String key, String value) Sets an option for an engine, language or instrument.
Engine.Builder	options(Map<String,String> options) Shortcut for setting multiple options using a map.
Engine.Builder	out(OutputStream out) Sets the standard output stream to be used for this engine.
Engine.Builder	sandbox(SandboxPolicy policy) Sets a code sandbox policy to an engine.
Engine.Builder	serverTransport(MessageTransport serverTransport) Take over transport of message communication with a server peer.
Engine.Builder	useSystemProperties(boolean enabled) Specifies whether the engine should use system properties if no explicit option is set.

Methods inherited from class java.lang.Object

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

Method Detail

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:

To specify option values directly., To build the engine instance.

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.

Since:

19.0

See Also:

To list all available options for engines., To list all available options for a {@link Language language}., To list all available options for an {@link Instrument instrument}.

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:

SandboxPolicy

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:

To set a single option.

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:

MessageTransport

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