TruffleLanguage.Env

java.lang.Object
- com.oracle.truffle.api.TruffleLanguage.Env

Enclosing class:

TruffleLanguage<C>
```
public static final class TruffleLanguage.Env
extends Object
```
Represents execution environment of the TruffleLanguage. Each active TruffleLanguage receives instance of the environment before any code is executed upon it. The environment has knowledge of all active languages and can exchange symbols between them.

Since:

0.8 or earlier

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addToHostClassPath(TruffleFile entry)` Adds an entry to the Java host class loader.
`Object`	`asBoxedGuestValue(Object guestObject)` Wraps primitive interop values in a TruffleObject exposing their methods as members.
`Object`	`asGuestValue(Object hostObject)` Converts a existing Java host object to a guest language value.
`Throwable`	`asHostException(Throwable exception)` Unwraps a host exception thrown by a Java method invocation.
`Object`	`asHostObject(Object value)` Returns the java host representation of a Truffle guest object if it represents a Java host language object.
`Object`	`asHostSymbol(Class<?> symbolClass)` Converts a Java class to a host symbol as if by `lookupHostSymbol(symbolClass.getName())` but without an actual lookup.
`Thread`	`createThread(Runnable runnable)` Creates a new thread that has access to the current language context.
`Thread`	`createThread(Runnable runnable, TruffleContext context)` Creates a new thread that has access to the given context.
`Thread`	`createThread(Runnable runnable, TruffleContext context, ThreadGroup group)` Creates a new thread that has access to the given context.
`Thread`	`createThread(Runnable runnable, TruffleContext context, ThreadGroup group, long stackSize)` Creates a new thread that has access to the given context.
`OutputStream`	`err()` Standard error writer provided by `Context.Builder.err(OutputStream)` this language is being executed in.
`void`	`exportSymbol(String symbolName, Object value)` Explicitly exports a symbol to the polyglot bindings object.
`Object`	`findMetaObject(Object value)` Find a meta-object of a value, if any.
`String[]`	`getApplicationArguments()` Returns the application arguments that were provided for this context.
`Map<String,Object>`	`getConfig()` Configuration arguments passed from an outer language context to an inner language context.
`TruffleContext`	`getContext()` Returns the polyglot context associated with this environment.
`Map<String,InstrumentInfo>`	`getInstruments()` Returns a map instrument-id to instrument instance of all instruments that are installed in the environment.
`Map<String,LanguageInfo>`	`getLanguages()` Returns a map mime-type to language instance of all languages that are installed in the environment.
`org.graalvm.options.OptionValues`	`getOptions()` Returns option values for the options described in `TruffleLanguage.getOptionDescriptors()`.
`Object`	`getPolyglotBindings()` Returns a TruffleObject that represents the polyglot bindings.
`TruffleFile`	`getTruffleFile(String path)` Returns a `TruffleFile` for given path.
`TruffleFile`	`getTruffleFile(URI uri)` Returns a `TruffleFile` for given `URI`.
`Object`	`importSymbol(String symbolName)` Explicitly imports a symbol from the polyglot bindings.
`InputStream`	`in()` Input stream provided by `Context.Builder.in(InputStream)` this language is being executed in.
`boolean`	`isCreateThreadAllowed()` Returns `true` if the creation of new threads is allowed in the current environment.
`boolean`	`isHostException(Throwable exception)` Tests whether an exception is a host exception thrown by a Java Interop method invocation.
`boolean`	`isHostFunction(Object value)` Returns `true` if the argument is a Java host language function wrapped using Truffle interop.
`boolean`	`isHostLookupAllowed()` Returns `true` if host access is generally allowed.
`boolean`	`isHostObject(Object value)` Returns `true` if the argument is Java host language object wrapped using Truffle interop.
`boolean`	`isHostSymbol(Object guestObject)` Returns `true` if the argument is a host symbol, representing the constructor and static members of a Java class, as obtained by e.g.
`boolean`	`isMimeTypeSupported(String mimeType)` Allows it to be determined if this `Context` can execute code written in a language with a given MIME type.
`boolean`	`isNativeAccessAllowed()` Returns `true` if access to native code is generally allowed.
`<T> T`	`lookup(Class<T> type)` Looks additional service up.
`<S> S`	`lookup(InstrumentInfo instrument, Class<S> type)` Returns an additional service provided by this instrument, specified by type.
`<S> S`	`lookup(LanguageInfo language, Class<S> type)` Returns an additional service provided by the given language, specified by type.
`Object`	`lookupHostSymbol(String symbolName)` Looks up a Java class in the top-most scope the host environment.
`TruffleContext.Builder`	`newContextBuilder()` Returns a new context builder useful to create inner context instances.
`OutputStream`	`out()` Standard output writer provided by `Context.Builder.out(OutputStream)` this language is being executed in.
`CallTarget`	`parse(Source source, String... argumentNames)` Evaluates source of (potentially different) language.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - getOptions
```
public org.graalvm.options.OptionValues getOptions()
```
    Returns option values for the options described in TruffleLanguage.getOptionDescriptors(). The returned options are never null.
    
    Since:
    
    0.27
  - getApplicationArguments
```
public String[] getApplicationArguments()
```
    Returns the application arguments that were provided for this context. The arguments array and its elements are never null. It is up to the language implementation whether and how they are accessible within the guest language scripts.
    
    Since:
    
    0.27
  - isCreateThreadAllowed
```
public boolean isCreateThreadAllowed()
```
    Returns true if the creation of new threads is allowed in the current environment.
    
    Since:
    
    0.28
    
    See Also:
    
    TruffleLanguage.Env.createThread(Runnable)
  - createThread
```
public Thread createThread(Runnable runnable)
```
    Creates a new thread that has access to the current language context. See TruffleLanguage.Env.createThread(Runnable, TruffleContext, ThreadGroup, long) for a detailed description of the parameters. The group is null and stackSize set to 0.
    
    Since:
    
    0.28
  - createThread
```
public Thread createThread(Runnable runnable,
                           TruffleContext context)
```
    Creates a new thread that has access to the given context. See TruffleLanguage.Env.createThread(Runnable, TruffleContext, ThreadGroup, long) for a detailed description of the parameters. The group is null and stackSize set to 0.
    
    Since:
    
    0.28
    
    See Also:
    
    TruffleLanguage.Env.getContext(), TruffleLanguage.Env.newContextBuilder()
  - createThread
```
public Thread createThread(Runnable runnable,
                           TruffleContext context,
                           ThreadGroup group)
```
    Creates a new thread that has access to the given context. See TruffleLanguage.Env.createThread(Runnable, TruffleContext, ThreadGroup, long) for a detailed description of the parameters. The stackSize set to 0.
    
    Since:
    
    0.28
    
    See Also:
    
    TruffleLanguage.Env.getContext(), TruffleLanguage.Env.newContextBuilder()
  - createThread
```
public Thread createThread(Runnable runnable,
                           TruffleContext context,
                           ThreadGroup group,
                           long stackSize)
```
    Creates a new thread that has access to the given context. A thread is initialized when it is started and disposed as soon as the thread finished the execution.
    It is recommended to set an uncaught exception handler for the created thread. For example the thread can throw an uncaught exception if one of the initialized language contexts don't support execution on this thread.
    The language that created and started the thread is responsible to complete all running or waiting threads when the context is disposed.
    The TruffleContext can be either an inner context created by TruffleLanguage.Env.newContextBuilder().build(), or the context associated with this environment obtained from TruffleLanguage.Env.getContext().
    
    Parameters:
    
    runnable - the runnable to run on this thread.
    
    context - the context to enter and leave when the thread is started.
    
    group - the thread group, passed on to the underlying Thread.
    
    stackSize - the desired stack size for the new thread, or zero if this parameter is to be ignored.
    
    Throws:
    
    IllegalStateException - if thread creation is not allowed.
    
    Since:
    
    0.28
    
    See Also:
    
    TruffleLanguage.Env.getContext(), TruffleLanguage.Env.newContextBuilder()
  - newContextBuilder
```
public TruffleContext.Builder newContextBuilder()
```
    Returns a new context builder useful to create inner context instances.
    
    Since:
    
    0.27
    
    See Also:
    
    for details on language inner contexts.
  - getPolyglotBindings
```
public Object getPolyglotBindings()
```
    Returns a TruffleObject that represents the polyglot bindings. The polyglot bindings consists of a set of symbols that have been exported explicitly by the languages or the embedder. This set of symbols allows for data exchange between polyglot languages. The polyglot bindings is separate from language bindings. The symbols can by read using string identifiers, a list of symbols may be requested with the keys message. Existing identifiers are removable, modifiable, readable and any new identifiers are insertable.
    
    Since:
    
    0.32
  - importSymbol
```
public Object importSymbol(String symbolName)
```
    Explicitly imports a symbol from the polyglot bindings. The behavior of this method is equivalent to sending a READ message to the polyglot bindings object. Reading a symbol that does not exist will return null.
    The returned symbol value can either be a TruffleObject (e.g. a native object from the other language) to support interoperability between languages, String or one of the Java primitive wrappers ( Integer, Double, Byte, Boolean, etc.).
    
    Parameters:
    
    symbolName - the name of the symbol to search for
    
    Returns:
    
    object representing the symbol or null if it does not exist
    
    Since:
    
    0.8 or earlier
  - exportSymbol
```
public void exportSymbol(String symbolName,
                         Object value)
```
    Explicitly exports a symbol to the polyglot bindings object. The behavior of this method is equivalent to sending a WRITE message to the polyglot bindings object. Exporting a symbol with a null value will remove the symbol from the polyglot object.
    The exported symbol value can either be a TruffleObject (e.g. a native object from the other language) to support interoperability between languages, String or one of the Java primitive wrappers ( Integer, Double, Byte, Boolean, etc.).
    
    Parameters:
    
    symbolName - the name with which the symbol should be exported into the polyglot scope
    
    value - the value to export for
    
    Since:
    
    0.27
  - isHostLookupAllowed
```
public boolean isHostLookupAllowed()
```
    Returns true if host access is generally allowed. If this method returns false then TruffleLanguage.Env.lookupHostSymbol(String) will always fail.
    
    Since:
    
    0.27
  - addToHostClassPath
```
public void addToHostClassPath(TruffleFile entry)
```
    Adds an entry to the Java host class loader. All classes looked up with TruffleLanguage.Env.lookupHostSymbol(String) will lookup classes with this new entry. If the entry was already added then calling this method again for the same entry has no effect. Given entry must not be null.
    
    Throws:
    
    SecurityException - if the file is not readable.
    
    Since:
    
    1.0
  - lookupHostSymbol
```
public Object lookupHostSymbol(String symbolName)
```
    Looks up a Java class in the top-most scope the host environment. Throws an error if no symbol was found or the symbol was not accessible. Symbols might not be accessible if a class filter prevents access. The returned object is always a TruffleObject .
    
    Parameters:
    
    symbolName - the name of the symbol in the the host language.
    
    Since:
    
    0.27
  - isHostObject
```
public boolean isHostObject(Object value)
```
    Returns true if the argument is Java host language object wrapped using Truffle interop.
    
    Since:
    
    1.0
    
    See Also:
    
    TruffleLanguage.Env.asHostObject(Object)
  - asHostObject
```
public Object asHostObject(Object value)
```
    Returns the java host representation of a Truffle guest object if it represents a Java host language object. Throws ClassCastException if the provided argument is not a host object.
    
    Since:
    
    1.0
  - asGuestValue
```
public Object asGuestValue(Object hostObject)
```
    Converts a existing Java host object to a guest language value. If the value is already an interop value, then no conversion will be performed. Otherwise, the returned wraps the host object and provides support for the interop contract to access the java members. The interpretation of converted objects is described in Context.asValue(Object).
    This method should be used exclusively to convert already allocated Java objects to a guest language representation. To allocate new host objects users should use TruffleLanguage.Env.lookupHostSymbol(String) to lookup the class and then send a NEW interop message to that object to instantiate it. This method does not respect configured class filters.
    
    Parameters:
    
    hostObject - the host object to convert
    
    Since:
    
    1.0
  - asBoxedGuestValue
```
public Object asBoxedGuestValue(Object guestObject)
```
    Wraps primitive interop values in a TruffleObject exposing their methods as members. By default primitive host values are not wrapped in TruffleObjects to expose their members. This method is intended for compatibility with existing Java interop APIs that expect such behavior. This method boxes the following primitive interop values: Boolean, Byte, Short, Integer, Long, Float, Double , Character, String. If the provided value is already boxed then the current value will be returned. If the provided value is not an interop value then an IllegalArgumentException will be thrown.
    
    Parameters:
    
    guestObject - the primitive guest value to box
    
    Throws:
    
    IllegalArgumentException - if value is an invalid interop value.
    
    Since:
    
    1.0
    
    See Also:
    
    TruffleLanguage.Env.asGuestValue(Object)
  - isHostFunction
```
public boolean isHostFunction(Object value)
```
    Returns true if the argument is a Java host language function wrapped using Truffle interop.
    
    Since:
    
    1.0
  - findMetaObject
```
public Object findMetaObject(Object value)
```
    Find a meta-object of a value, if any. The meta-object represents a description of the object, reveals it's kind and it's features. Some information that a meta-object might define includes the base object's type, interface, class, methods, attributes, etc.
    When no meta-object is known, returns null. The meta-object is an interop value. An interop value can be either a TruffleObject (e.g. a native object from the other language) to support interoperability between languages or a String.
    
    Parameters:
    
    value - the value to find the meta object for.
    
    Since:
    
    1.0
  - isHostException
```
public boolean isHostException(Throwable exception)
```
    Tests whether an exception is a host exception thrown by a Java Interop method invocation. Host exceptions may be thrown by messages sent to Java objects that involve the invocation of a Java method or constructor (EXECUTE, INVOKE, NEW). The host exception may be unwrapped using TruffleLanguage.Env.asHostException(Throwable).
    
    Parameters:
    
    exception - the Throwable to test
    
    Returns:
    
    true if the exception is a host exception, false otherwise
    
    Since:
    
    1.0
    
    See Also:
    
    TruffleLanguage.Env.asHostException(Throwable)
  - asHostException
```
public Throwable asHostException(Throwable exception)
```
    Unwraps a host exception thrown by a Java method invocation. Host exceptions may be thrown by messages sent to Java objects that involve the invocation of a Java method or constructor (EXECUTE, INVOKE, NEW). Host exceptions can be identified using TruffleLanguage.Env.isHostException(Throwable) .
    
    Parameters:
    
    exception - the host exception to unwrap
    
    Returns:
    
    the original Java exception
    
    Throws:
    
    IllegalArgumentException - if the exception is not a host exception
    
    Since:
    
    1.0
    
    See Also:
    
    TruffleLanguage.Env.isHostException(Throwable)
  - isHostSymbol
```
public boolean isHostSymbol(Object guestObject)
```
    Returns true if the argument is a host symbol, representing the constructor and static members of a Java class, as obtained by e.g. TruffleLanguage.Env.lookupHostSymbol(java.lang.String).
    
    Since:
    
    1.0
    
    See Also:
    
    TruffleLanguage.Env.lookupHostSymbol(String)
  - asHostSymbol
```
public Object asHostSymbol(Class<?> symbolClass)
```
    Converts a Java class to a host symbol as if by lookupHostSymbol(symbolClass.getName()) but without an actual lookup. Must not be used with Truffle or guest language classes.
    
    Since:
    
    1.0
    
    See Also:
    
    TruffleLanguage.Env.lookupHostSymbol(String)
  - isNativeAccessAllowed
```
public boolean isNativeAccessAllowed()
```
    Returns true if access to native code is generally allowed. If this method returns false then loading native libraries with the Truffle NFI will fail.
    
    Since:
    
    1.0
  - isMimeTypeSupported
```
public boolean isMimeTypeSupported(String mimeType)
```
    Allows it to be determined if this Context can execute code written in a language with a given MIME type.
    
    Returns:
    
    a boolean that indicates if the MIME type is supported
    
    Since:
    
    0.11
    
    See Also:
    
    Source.getMimeType(), TruffleLanguage.Env.parse(Source, String...)
  - parse
```
public CallTarget parse(Source source,
                        String... argumentNames)
```
    Evaluates source of (potentially different) language. The MIME type is used to identify the TruffleLanguage to use to perform the TruffleLanguage.parse(com.oracle.truffle.api.TruffleLanguage.ParsingRequest) . The names of arguments are parameters for the resulting {#link CallTarget} that allow the source to reference the actual parameters passed to CallTarget.call(java.lang.Object...).
    
    Parameters:
    
    source - the source to evaluate
    
    argumentNames - the names of CallTarget.call(java.lang.Object...) arguments that can be referenced from the source
    
    Returns:
    
    the call target representing the parsed result
    
    Since:
    
    0.8 or earlier
  - in
```
public InputStream in()
```
    Input stream provided by Context.Builder.in(InputStream) this language is being executed in.
    
    Returns:
    
    reader, never null
    
    Since:
    
    0.8 or earlier
  - out
```
public OutputStream out()
```
    Standard output writer provided by Context.Builder.out(OutputStream) this language is being executed in.
    
    Returns:
    
    writer, never null
    
    Since:
    
    0.8 or earlier
  - err
```
public OutputStream err()
```
    Standard error writer provided by Context.Builder.err(OutputStream) this language is being executed in.
    
    Returns:
    
    writer, never null
    
    Since:
    
    0.8 or earlier
  - lookup
```
public <T> T lookup(Class<T> type)
```
    Looks additional service up. An environment for a particular language may also be associated with additional services. One can request implementations of such services by calling this method with the type identifying the requested service and its API. Services that can be obtained via this method include Instrumenter and others.
    
    Type Parameters:
    
    T - type of requested service
    
    Parameters:
    
    type - class of requested service
    
    Returns:
    
    instance of T or null if there is no such service available
    
    Since:
    
    0.12
  - lookup
```
public <S> S lookup(InstrumentInfo instrument,
                    Class<S> type)
```
    Returns an additional service provided by this instrument, specified by type. If an instrument is not enabled, it will be enabled automatically by requesting a supported service. If the instrument does not provide a service for a given type it will not be enabled automatically.
    
    Type Parameters:
    
    S - the requested type
    
    Parameters:
    
    instrument - identification of the instrument to query
    
    type - the class of the requested type
    
    Returns:
    
    the registered service or null if none is found
    
    Since:
    
    0.26
  - lookup
```
public <S> S lookup(LanguageInfo language,
                    Class<S> type)
```
    Returns an additional service provided by the given language, specified by type. If an language is not loaded, it will not be automatically loaded by requesting a service. In order to ensure a language to be loaded at least one Source must be parsed first.
    
    Type Parameters:
    
    S - the requested type
    
    Parameters:
    
    language - the language to query
    
    type - the class of the requested type
    
    Returns:
    
    the registered service or null if none is found
    
    Since:
    
    0.26
  - getLanguages
```
public Map<String,LanguageInfo> getLanguages()
```
    Returns a map mime-type to language instance of all languages that are installed in the environment. Using the language instance additional services can be looked up .
    
    Since:
    
    0.26
  - getInstruments
```
public Map<String,InstrumentInfo> getInstruments()
```
    Returns a map instrument-id to instrument instance of all instruments that are installed in the environment. Using the instrument instance additional services can be looked up .
    
    Since:
    
    0.26
  - getConfig
```
public Map<String,Object> getConfig()
```
    Configuration arguments passed from an outer language context to an inner language context. Inner language contexts can be created using TruffleLanguage.Env.newContextBuilder().
    
    Since:
    
    0.11
    
    See Also:
    
    to create inner contexts., to pass configuration objects to the inner context.
  - getContext
```
public TruffleContext getContext()
```
    Returns the polyglot context associated with this environment.
    
    Returns:
    
    the polyglot context
    
    Since:
    
    0.30
  - getTruffleFile
```
public TruffleFile getTruffleFile(String path)
```
    Returns a TruffleFile for given path.
    
    Parameters:
    
    path - the absolute or relative path to create TruffleFile for
    
    Returns:
    
    TruffleFile
    
    Since:
    
    1.0
  - getTruffleFile
```
public TruffleFile getTruffleFile(URI uri)
```
    Returns a TruffleFile for given URI.
    
    Parameters:
    
    uri - the URI to create TruffleFile for
    
    Returns:
    
    TruffleFile
    
    Since:
    
    1.0

Class TruffleLanguage.Env

Method Summary

Methods inherited from class java.lang.Object

Method Detail

getOptions

getApplicationArguments

isCreateThreadAllowed

createThread

createThread

createThread

createThread

newContextBuilder

getPolyglotBindings

importSymbol

exportSymbol

isHostLookupAllowed

addToHostClassPath

lookupHostSymbol

isHostObject

asHostObject

asGuestValue

asBoxedGuestValue

isHostFunction

findMetaObject

isHostException

asHostException

isHostSymbol

asHostSymbol

isNativeAccessAllowed

isMimeTypeSupported

parse

in

out

err

lookup

lookup

lookup

getLanguages

getInstruments

getConfig

getContext

getTruffleFile

getTruffleFile