[GR-41686] Document new type mapping features for embedded espresso. contexts

PullRequest: graal/12913

Author: javeleon

docs/reference-manual/java-on-truffle/Interoperability.md

@@ -149,6 +149,8 @@ A number of useful context option can be set with `contextBuilder.option(key, va
 * `java.Verify` can be set to `none`, `remove`, or `all` to control whether bytecode verification does not happen, only happens on user code, or happens for all classes.
 * `java.JDWPOptions` can be set to setup and enable debugging over JDWP. For example, it could be set to `transport=dt_socket,server=y,address=localhost:8000,suspend=y`.
 * `java.Polyglot` can be set to `true` or `false` to allow or deny access to the polyglot features from the `com.oracle.truffle.espresso.polyglot` package.
+* `java.PolyglotTypeConverters` can be set to declare a type conversion function that maps a meta qualified name to a type converter class. Please refer to more details in a dedicated section below.
+* `java.PolyglotInterfaceMappings` can be set to a semicolon-separated list of 1:1 interface type mappings to automatically construct guest proxies for host objects that implement declared interfaces in the list. Please refer to more details in a dedicated section below.
 
 ***Java on Truffle does not support evaluation (`.eval`) of Java sources.**
 
@@ -183,6 +185,79 @@ assert java_lang_Integer.equals(integer_class.getMember("static"));
 assert java_lang_Number.equals(java_lang_Integer.getMember("super"));
 ```
 
+### Converting host objects to guest types using type converters
+
+Since version 22.3.0 Java on Truffle has built-in support for declaring type conversion of host objects to proper guest-typed objects. This is done via context builder options as described above. The main idea is to allow transparent flow of objects from host to guest without having to perform guest type checks when host objects enter an embedded Java on Truffle context. Specifically the follwoing options can be set to control type conversion for an embedded context:
+
+#### java.PolyglotTypeConverters
+This option takes precedence over `java.PolyglotInterfaceMappings` and thus, if a dedicated type converter function is defined, no other automatic interface mapping proxies are generated by Java on Truffle. 
+
+*Note: Declared type converters must implement the `GuestTypeConversion` interface located in the `com.oracle.truffle.espresso.polyglot` package in `polyglor.jar`.*
+```java
+package com.oracle.truffle.espresso.polyglot;
+
+public interface GuestTypeConversion<T> {
+    T toGuest(Object polyglotInstance);
+}
+```
+
+For each type converter declared use one option call like this:
+
+```java
+// host java
+Context polyglot = Context.newBuilder().allowAllAccess(true).
+        option("java.PolyglotTypeConverters.java.math.BigDecimal", "guest.context.path.BigDecimalConverter").
+        build();
+...
+
+// guest java
+package guest.context.path;
+
+import com.oracle.truffle.espresso.polyglot.GuestTypeConversion;
+import com.oracle.truffle.espresso.polyglot.Interop;
+import com.oracle.truffle.espresso.polyglot.InteropException;
+
+import java.math.BigDecimal;
+
+public class BigDecimalConverter implements GuestTypeConversion<BigDecimal> {
+
+    @Override
+    @SuppressWarnings("unchecked")
+    public BigDecimal toGuest(Object polyglotInstance) {
+        try {
+            return new BigDecimal(Interop.asString(Interop.invokeMember(polyglotInstance, "toString")));
+        } catch (InteropException e) {
+            throw new ClassCastException("polyglot instance cannot be cast to java.math.BigDecimal");
+        }
+    }
+}
+
+```
+The `java.math.Bigdecimal` part of the option declares the fully qualified meta name of a host object entering Java on Truffle.
+
+#### java.PolyglotInterfaceMappings
+
+If there are no dedicated `java.PolyglotTypeConverters` for a host object flowing into an embedded Java on Truffle context, automatic interface type mapping kicks in. `java.PolyglotInterfaceMappings` enables seamless interface type sharing between the host and the embedded context. 
+
+The following example shows how this option can be used to allow passing common JDK collection types by interface to an embedded Java on Truffle context:
+
+```java
+// host java
+builder.option("java.PolyglotInterfaceMappings", getInterfaceMappings());
+
+
+private static String getInterfaceMappings(){
+    return "java.lang.Iterable;"+
+    "java.util.Collection;"+
+    "java.util.List;"+
+    "java.util.Set;"+
+    "java.util.Map;"+
+    "java.util.Iterator;"+
+    "java.util.Spliterator;";
+}
+
+```
+
 ## Multithreading
 
 Java on Truffle is designed to be a multi-threaded language and much of the ecosystem expects threads to be available.

espresso/CHANGELOG.md

@@ -4,6 +4,9 @@
 ### User-visible changes
 * Interop invokable members of espresso objects can now also be read.
 * Added the `addPath` invokable member to Espresso Bindings if `java.UseBindingsLoader=true`. Allows adding new path to the classloader associated with the bindings.
+* Added option `java.PolyglotTypeConverters` that can be set to declare a type conversion function that maps a host meta qualified name to a type converter class in an embedded Espresso context.
+* Added option`java.PolyglotInterfaceMappings` that can be set to a semicolon-separated list of 1:1 interface type mappings to automatically construct guest proxies for host objects that implement declared interfaces in the list.
+
 ### Internal changes
 ### Noteworthy fixes
 * Fix some conversions at interop boundaries: when an espresso-to-espresso conversion was seen, then an espresso-to-primitive conversion happens. The latter would fail.