com.oracle.truffle.espresso.polyglot

Class Polyglot

java.lang.Object

com.oracle.truffle.espresso.polyglot.Polyglot

public final class Polyglot
extends Object

Polyglot API for Espresso.

Allows Espresso to interact with other Truffle languages by evaluating code in a different language, importing symbols, exported by other languages and making Espresso objects available to other languages by exporting them.

Foreign values, obtained from Polyglot.eval(java.lang.String, java.lang.String) or Polyglot.importObject(java.lang.String), are returned as Object. There are two options to make their members accessible from Espresso:

• Polyglot.cast the object to a Java interface. In this case, method calls to the interface methods will be forwarded to the foreign object.
• Polyglot.cast the object to a Java class. In this case, accesses to the class fields will be forwarded to the foreign object, but the Java implementations of the methods will be used.

Casting to abstract classes is not supported.

NB: for Java code running in Espresso, these methods will be intrinsified. Otherwise multi-language environment is not available.

Since:

21.0

Method Summary

Modifier and Type	Method and Description
static <T> T	cast(Class<? extends T> targetClass, Object value) If a regular Class.cast(java.lang.Object) of value to targetClass succeeds, Polyglot.cast succeeds too.
static Object	eval(String languageId, String sourceCode) Evaluates the given code in the given language.
static <T> T	eval(String languageId, String sourceCode, Class<? extends T> targetClass) Evaluates the given code in the given language, and casts the result to the given class.
static void	exportObject(String name, Object value) Exports value under name to the Polyglot scope.
static Object	importObject(String name) Imports name from global Polyglot scope.
static <T> T	importObject(String name, Class<? extends T> targetClass) Imports name from global Polyglot scope and casts the result to the given class.
static boolean	isForeignObject(Object object) Tests if an object is a foreign value, i.e.

Methods inherited from class java.lang.Object

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

Method Detail

isForeignObject

public static boolean isForeignObject(Object object)

Tests if an object is a foreign value, i.e. originates from a different Truffle language.

Since:

21.0

cast

public static <T> T cast(Class<? extends T> targetClass,
                         Object value)
                  throws ClassCastException

If a regular Class.cast(java.lang.Object) of value to targetClass succeeds, Polyglot.cast succeeds too. In addition, if value is a foreign object:

• if targetClass is a primitive class, converts the foreign value to this type and returns the result as a boxed type. To avoid eager conversion, cast to the corresponding wrapper class.
• if targetClass is a wrapper class, checks that the foreign value is a number, a boolean or a character respectively, and returns a wrapper of the foreign value. When the value field of the result is accessed, the current value of the foreign primitive is fetched.
• if targetClass is an array class and the foreign value has array elements, returns the foreign value as targetClass.
• if targetClass is a (non-abstract, non-wrapper) class, checks that all the instance fields defined in the class or its ancestors exist in the foreign object. Returns the foreign object as targetClass.
• if targetClass is an interface, returns the foreign object as targetClass. The existence of methods, defined in targetClass, is not verified and if a method does not exist, an exception will be thrown only when the method is invoked.

Throws:

NullPointerException - is targetClass is null

ClassCastException -

• if value is a foreign object, targetClass is a primitive type but value does not represent an object of this primitive type
• if value is a foreign object, targetClass is an array type but value does not have array elements
• if value is a foreign object, targetClass is an abstract class and value was not previously cast to a concrete descendant of targetClass
• if value is a foreign object, targetClass is a class and a field of targetClass does not exist in the object
• if value is a regular Espresso object and cannot be cast to targetClass

Since:

21.0

eval

public static Object eval(String languageId,
                          String sourceCode)

Evaluates the given code in the given language.

To access members of the foreign object, write a corresponding class or interface stub in Java and cast the eval result to it using Polyglot.cast.

Parameters:

languageId - the id of one of the Truffle languages

sourceCode - the source code in the language, identified by languageId

Returns:

the result of the evaluation as Object.

Throws:

IllegalArgumentException -

• if the language is not available
• if parsing of the code fails

Since:

21.0

eval

public static <T> T eval(String languageId,
                         String sourceCode,
                         Class<? extends T> targetClass)
                  throws ClassCastException

Evaluates the given code in the given language, and casts the result to the given class.

See Polyglot.cast(java.lang.Class<? extends T>, java.lang.Object) for the details of casting.

Parameters:

languageId - id of one of the Truffle languages

Throws:

ClassCastException

Since:

21.0

importObject

public static Object importObject(String name)

Imports name from global Polyglot scope. If name does not exist in the scope, returns null. The foreign value is returned as Object.

To access the foreign object's members, write a corresponding class or interface stub in Java and cast the eval result to it using Polyglot.cast.

Since:

21.0

importObject

public static <T> T importObject(String name,
                                 Class<? extends T> targetClass)
                          throws ClassCastException

Imports name from global Polyglot scope and casts the result to the given class.

See Polyglot.cast(java.lang.Class<? extends T>, java.lang.Object) for the details of casting.

Throws:

ClassCastException

Since:

21.0

exportObject

public static void exportObject(String name,
                                Object value)

Exports value under name to the Polyglot scope.

Since:

21.0