JavaInterop

java.lang.Object
- com.oracle.truffle.api.interop.java.JavaInterop

```
public final class JavaInterop
extends Object
```
Helper methods to simplify access to objects of Truffle languages from Java and the other way around. The Java/Truffle interop builds on mutual interoperability between individual Truffle languages - it just encapsulates it into Java facade to make it as natural to access foreign Truffle objects as Java programmers are used to when accessing Java objects and interfaces directly.
Java/Truffle Object Inter-op Semantics
In case your language exposes a TruffleObject implementation, and somebody wraps your object into a JavaInterop interface via JavaInterop.asJavaObject(java.lang.Class, com.oracle.truffle.api.interop.TruffleObject) method, this is the set of messages you can expect:
Users can send you any message by annotating their interface method with MethodMessage and it is up to them (and you) to negotiate the correct set of messages and their parameters to help you understand each other. However there is a default set of messages (for methods not annotated by MethodMessage) which consists of:
1. First of all Message.createInvoke(int) is constructed (with the number of parameters of the interface method) and delivered to your object. The receiver of the message is your TruffleObject. The first argument is name of the interface method, followed by the actual arguments of the interface method. Your language can either handle the message or throw UnsupportedMessageException to signal additional processing is needed.
2. If the previous message isn't handled, a Message.READ is sent to your object (e.g. receiver) with a field name equal to the name of the interface method. If the read returns a primitive type, it is returned.
3. If the read value is another TruffleObject, it is inspected whether it handles Message.IS_EXECUTABLE. If it does, a message Message.createExecute(int) with name of the interface method and its parameters is sent to the object. The result is returned to the interface method caller.
4. In case the read value is neither primitive, neither executable , and the interface method has no parameters, it is returned back.
5. All other cases yield an InteropException.
Object oriented languages are expected to handle the initial Message.createInvoke(int) message. Non-OOP languages are expected to ignore it, yield UnsupportedMessageException and handle the subsequent read and execute ones. The real semantic however depends on the actual language one is communicating with.

Setting the Java Interop Up
When configuring your PolyglotEngine you can use PolyglotEngine.Builder.globalSymbol(java.lang.String, java.lang.Object) method to create references to classes with static methods and fields or instance methods or fields as shown in following example:
```
public static final class Multiplier {
    public static int mul(int x, int y) {
        return x * y;
    }
}

public interface Multiply {
    int mul(int x, int y);
}

public static PolyglotEngine configureJavaInterop(Multiply multiply) {
    TruffleObject staticAccess = JavaInterop.asTruffleObject(Multiplier.class);
    TruffleObject instanceAccess = JavaInterop.asTruffleObject(multiply);

    PolyglotEngine engine = PolyglotEngine.newBuilder().
        globalSymbol("mul", staticAccess).
        globalSymbol("compose", instanceAccess).
        build();

    return engine;
}
```
After that objects mul and compose are available for import from any Truffe language.
Since:

0.9

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static <T> T`	`asJavaFunction(Class<T> functionalType, TruffleObject function)` Takes executable object from a `TruffleLanguage` and converts it into an instance of a Java functional interface.
`static <T> T`	`asJavaObject(Class<T> type, TruffleObject foreignObject)` Wraps a `foreign object` into easy to use interface.
`static <T> TruffleObject`	`asTruffleFunction(Class<T> functionalType, T implementation)` Takes a functional interface and its implementation (for example lambda function) and converts it into object executable by Truffle languages.
`static TruffleObject`	`asTruffleObject(Object obj)` Exports a Java object for use in any `TruffleLanguage`.
`static Object`	`asTruffleValue(Object obj)` Prepares a Java object for use in any `TruffleLanguage`.
`static int`	`getKeyInfo(TruffleObject foreignObject, Object propertyName)` Get information about an object property.
`static <K,V> Map<K,V>`	`getMapView(Map<K,V> map, boolean includeInternal)` Get a view of map created by `JavaInterop.asJavaObject(java.lang.Class, com.oracle.truffle.api.interop.TruffleObject)` with `Map.class` as an argument.
`static boolean`	`isArray(TruffleObject foreignObject)` Test whether the object represents an array.
`static boolean`	`isBoxed(TruffleObject foreignObject)` Test whether the object represents a boxed primitive type.
`static boolean`	`isJavaObject(Class<?> type, TruffleObject foreignObject)` Checks whether an `object` is a Java object of a given type.
`static boolean`	`isNull(TruffleObject foreignObject)` Test whether the object represents a `null` value.
`static boolean`	`isPrimitive(Object obj)` Test whether the object is a primitive, which all `TruffleLanguage`s are supposed to handle.
`static TruffleObject`	`toJavaClass(TruffleObject obj)` Finds a Java class representation for the provided object.
`static Object`	`unbox(TruffleObject foreignObject)` Convert the object into a Java primitive type.

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

- Method Detail
  - asJavaObject
```
public static <T> T asJavaObject(Class<T> type,
                                 TruffleObject foreignObject)
```
    Wraps a foreign object into easy to use interface. Imagine one wants to access a JavaScript object like:
```
 var obj = {
   'x' : 10,
   'y' : 3.3,
   'name' : 'Truffle'
 };
 
```
    from Java. One can do it by defining an interface:
```
 interface ObjAccess {
   int x();
   @MethodMessage(message = "WRITE")
   void x(int newValue);
   double y();
   String name();
 }
 
```
    and obtaining its instance by calling this conversion method:
```
 ObjAccess access = JavaInterop.asJavaObject(ObjAccess.class, obj);
 assert access.x() == 10 : "Still the default";
 access.x(5);
 assert access.x() == 5 : "Changed to five";
 
```
    Type Parameters:
    
    T - type of requested and returned value
    
    Parameters:
    
    type - interface modeling structure of foreignObject in Java
    
    foreignObject - object coming from a Truffle language, can be null, in such case the returned value will likely be null as well
    
    Returns:
    
    instance of requested interface granting access to specified foreignObject, can be null, if the foreignObject parameter was null
    
    Throws:
    
    ClassCastException - if the foreignObject cannot be converted to requested type
    
    Since:
    
    0.9
  - isJavaObject
```
public static boolean isJavaObject(Class<?> type,
                                   TruffleObject foreignObject)
```
    Checks whether an object is a Java object of a given type.
    Given some Java object x of type X, the following assertion will always pass.
```
 X x = ...;
 TruffleObject obj = JavaInterop.asTruffleObject(x);
 assert JavaInterop.isJavaObject(X.class, obj);
 
```
    Parameters:
    
    type - Java class that the object is tested for
    
    foreignObject - object coming from a Truffle language
    
    Returns:
    
    true if the foreignObject was created from an object of class type using JavaInterop.asTruffleObject(Object), false otherwise
    
    Since:
    
    0.24
  - asTruffleObject
```
public static TruffleObject asTruffleObject(Object obj)
```
    Exports a Java object for use in any TruffleLanguage. The system scans structure of provided object and exposes all public fields and methods to any Truffle language. An instance of class
```
 class JavaRecord {
   public int x;
   public double y;
   public String name() {
     return "Truffle";
   }
 }
 TruffleObject obj = JavaInterop.asTruffleObject(new JavaRecord());
 
```
    can then be access from JavaScript or any other Truffle based language as
```
 obj.x;
 obj.y;
 obj.name();
 
```
    One can also enumerate the properties of the object and see all three of them:
```
 for (var p in obj) {
   print(p); // yields x, y, name
 }
 
```
    When the obj represents a Class, then the created TruffleObject will allow access to public and static fields and methods from the class.
    Do not convert primitive types (instances of Number, Boolean, Character or String) to TruffleObject, all TruffleLanguages are supposed to handle primitives. Use directly the the primitive types instead. To convert generic objects to TruffleObject while retaining primitive values unwrapped, use JavaInterop.asTruffleValue(java.lang.Object) instead.
    Parameters:
    
    obj - a Java object to convert into one suitable for Truffle languages
    
    Returns:
    
    converted object
    
    Since:
    
    0.9
  - asTruffleValue
```
public static Object asTruffleValue(Object obj)
```
    Prepares a Java object for use in any TruffleLanguage. If the object is one of primitive values, it is just returned, as all TruffleLanguages are supposed to handle such object. If it is a non-primitive type of Java object, the method does exactly the same thing as JavaInterop.asTruffleObject(java.lang.Object).
    
    Parameters:
    
    obj - a Java object to convert into one suitable for Truffle languages
    
    Returns:
    
    converted object, or primitive
    
    Since:
    
    0.18
  - isPrimitive
```
public static boolean isPrimitive(Object obj)
```
    Test whether the object is a primitive, which all TruffleLanguages are supposed to handle. Primitives are instances of Number, Boolean, Character or String.
    
    Parameters:
    
    obj - a Java object to test
    
    Returns:
    
    true when the object is a primitive from TruffleLanguages point of view, false otherwise.
    
    Since:
    
    0.18
  - asJavaFunction
```
public static <T> T asJavaFunction(Class<T> functionalType,
                                   TruffleObject function)
```
    Takes executable object from a TruffleLanguage and converts it into an instance of a Java functional interface. If the functionalType method is using variable arguments, then the arguments are unwrapped and passed into the function as indivual arguments.
    
    Type Parameters:
    
    T - requested and returned type
    
    Parameters:
    
    functionalType - interface with a single defined method - so called functional interface
    
    function - Truffle that responds to Message.IS_EXECUTABLE and can be invoked
    
    Returns:
    
    instance of interface that wraps the provided function
    
    Since:
    
    0.9
  - asTruffleFunction
```
public static <T> TruffleObject asTruffleFunction(Class<T> functionalType,
                                                  T implementation)
```
    Takes a functional interface and its implementation (for example lambda function) and converts it into object executable by Truffle languages. Here is a definition of function returning the meaning of life as lambda expression, converting it back to Java and using it:
```
 TruffleObject to = JavaInterop.asTruffleFunction(Callable.class, () -> 42);
 Callable c = JavaInterop.asJavaFunction(Callable.class, to);
 assert c.call() == 42;
 
```
    Type Parameters:
    
    T - requested interface and implementation
    
    Parameters:
    
    functionalType - interface with a single defined method - so called functional interface
    
    implementation - implementation of the interface, or directly a lambda expression defining the required behavior
    
    Returns:
    
    an executable TruffleObject ready to be used in any Truffle language
    
    Since:
    
    0.9
  - isNull
```
public static boolean isNull(TruffleObject foreignObject)
```
    Test whether the object represents a null value.
    
    Parameters:
    
    foreignObject - object coming from a Truffle language, can be null.
    
    Returns:
    
    true when the object represents a null value, false otherwise.
    
    Since:
    
    0.18
    
    See Also:
    
    Message.IS_NULL
  - isArray
```
public static boolean isArray(TruffleObject foreignObject)
```
    Test whether the object represents an array. When an object has a size, it represents an array and can be converted to a list of array elements by:
```
 asJavaObject(java.util.List.class, foreignObject);
 
```
    Parameters:
    
    foreignObject - object coming from a Truffle language, can be null.
    
    Returns:
    
    true when the object represents an array, false otherwise.
    
    Since:
    
    0.18
    
    See Also:
    
    Message.HAS_SIZE
  - isBoxed
```
public static boolean isBoxed(TruffleObject foreignObject)
```
    Test whether the object represents a boxed primitive type.
    
    Parameters:
    
    foreignObject - object coming from a Truffle language, can be null.
    
    Returns:
    
    true when the object represents a boxed primitive type, false otherwise.
    
    Since:
    
    0.18
    
    See Also:
    
    Message.IS_BOXED
  - unbox
```
public static Object unbox(TruffleObject foreignObject)
```
    Convert the object into a Java primitive type. Primitive types are subclasses of Number, Boolean, Character and String.
    
    Parameters:
    
    foreignObject - object coming from a Truffle language, which is known (check JavaInterop.isBoxed(com.oracle.truffle.api.interop.TruffleObject)) to be a boxed Java primitive type.
    
    Returns:
    
    An object representation of Java primitive type, or null when the unboxing was not possible.
    Since: 0.18 See Also: Message.UNBOX
  getKeyInfo public static int getKeyInfo(TruffleObject foreignObject, Object propertyName) Get information about an object property. Parameters: foreignObject - object coming from a Truffle language propertyName - name of a property or index of an array Returns: an integer representing KeyInfo bit flags. Since: 0.26 See Also: Message.KEY_INFO, KeyInfo getMapView public static <K,V> Map<K,V> getMapView(Map<K,V> map, boolean includeInternal) throws IllegalArgumentException Get a view of map created by JavaInterop.asJavaObject(java.lang.Class, com.oracle.truffle.api.interop.TruffleObject) with Map.class as an argument. The view includes or excludes internal elements based on includeInternal parameter. Parameters: map - a map obtained by JavaInterop.asJavaObject(java.lang.Class, com.oracle.truffle.api.interop.TruffleObject) includeInternal - true to include internal elements in the map, false to exclude them. Returns: a view of the original map with a possibly changed set of elements depending on the includeInternal argument. Throws: IllegalArgumentException - when the Map was not created by JavaInterop.asJavaObject(java.lang.Class, com.oracle.truffle.api.interop.TruffleObject) . Since: 0.26 toJavaClass public static TruffleObject toJavaClass(TruffleObject obj) Finds a Java class representation for the provided object. If the object was created via asTruffleObject(original) call, then it is unwrapped and the result is equal to asTruffleObject(original.getClass()). This method works only on objects that wrap plain Java objects. Parameters: obj - object expected to be created by JavaInterop.asTruffleObject(java.lang.Object) or similar methods Returns: object representing wrapper around original Java object's type if any. Otherwise null Since: 0.26

Class JavaInterop

Java/Truffle Object Inter-op Semantics

Setting the Java Interop Up

Method Summary

Methods inherited from class java.lang.Object

Method Detail

asJavaObject

isJavaObject

asTruffleObject

asTruffleValue

isPrimitive

asJavaFunction

asTruffleFunction

isNull

isArray

isBoxed

unbox

getKeyInfo

getMapView

toJavaClass