org.graalvm.polyglot

Class HostAccess.Builder

java.lang.Object

org.graalvm.polyglot.HostAccess.Builder

Enclosing class:

HostAccess

public final class HostAccess.Builder
extends Object

Builder to create a custom host access policy.

Since:

19.0

Method Summary

Modifier and Type	Method and Description
HostAccess.Builder	allowAccess(Executable element) Allows access to a given constructor or method.
HostAccess.Builder	allowAccess(Field element) Allows access to a given field.
HostAccess.Builder	allowAccessAnnotatedBy(Class<? extends Annotation> annotation) Allows access to public constructors, methods or fields of public classes that were annotated by the given annotation class.
HostAccess.Builder	allowAllImplementations(boolean allow) Allow guest languages to implement any Java interface.
HostAccess.Builder	allowArrayAccess(boolean arrayAccess) Allows the guest application to access arrays as values with array elements.
HostAccess.Builder	allowImplementations(Class<?> interfaceClass) Allow implementations of this type by the guest language.
HostAccess.Builder	allowImplementationsAnnotatedBy(Class<? extends Annotation> annotation) Allow implementations of types annotated with the given annotation.
HostAccess.Builder	allowListAccess(boolean listAccess) Allows the guest application to access lists as values with array elements.
HostAccess.Builder	allowPublicAccess(boolean allow) Allows unrestricted access to all public constructors, methods or fields of public classes.
HostAccess	build() Creates an instance of the custom host access configuration.
HostAccess.Builder	denyAccess(Class<?> clazz) Prevents access to members of given class and its subclasses.
HostAccess.Builder	denyAccess(Class<?> clazz, boolean includeSubclasses) Prevents access to members of given class.
<S,T> HostAccess.Builder	targetTypeMapping(Class<S> sourceType, Class<T> targetType, Predicate<S> accepts, Function<S,T> converter) Adds a custom source to target type mapping for Java host calls, host field assignments and explicit value conversions.

Methods inherited from class java.lang.Object

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

Method Detail

allowAccessAnnotatedBy

public HostAccess.Builder allowAccessAnnotatedBy(Class<? extends Annotation> annotation)

Allows access to public constructors, methods or fields of public classes that were annotated by the given annotation class.

Since:

19.0

allowPublicAccess

public HostAccess.Builder allowPublicAccess(boolean allow)

Allows unrestricted access to all public constructors, methods or fields of public classes. Note that this policy allows unrestricted access to reflection. It is highly discouraged from using this option in environments where the guest application is not fully trusted.

Since:

19.0

allowAccess

public HostAccess.Builder allowAccess(Executable element)

Allows access to a given constructor or method. Note that the method or constructor must be public in order to have any effect.

Since:

19.0

allowAccess

public HostAccess.Builder allowAccess(Field element)

Allows access to a given field. Note that the field must be public in order to have any effect.

Since:

19.0

denyAccess

public HostAccess.Builder denyAccess(Class<?> clazz)

Prevents access to members of given class and its subclasses.

Parameters:

clazz - the class to deny access to

Returns:

this builder

Since:

19.0

denyAccess

public HostAccess.Builder denyAccess(Class<?> clazz,
                                     boolean includeSubclasses)

Prevents access to members of given class.

Parameters:

clazz - the class to deny access to

includeSubclasses - should subclasses be excuded as well?

Returns:

this builder

Since:

19.0

allowAllImplementations

public HostAccess.Builder allowAllImplementations(boolean allow)

Allow guest languages to implement any Java interface.

Since:

19.0

See Also:

HostAccess.ALL

allowImplementationsAnnotatedBy

public HostAccess.Builder allowImplementationsAnnotatedBy(Class<? extends Annotation> annotation)

Allow implementations of types annotated with the given annotation. For the explicit host access present the HostAccess.Implementable annotation is configured for this purpose.

Since:

19.0

See Also:

HostAccess.Implementable

allowImplementations

public HostAccess.Builder allowImplementations(Class<?> interfaceClass)

Allow implementations of this type by the guest language.

Since:

19.0

allowArrayAccess

public HostAccess.Builder allowArrayAccess(boolean arrayAccess)

Allows the guest application to access arrays as values with array elements. By default no array access is allowed.

Since:

19.0

See Also:

Value.hasArrayElements()

allowListAccess

public HostAccess.Builder allowListAccess(boolean listAccess)

Allows the guest application to access lists as values with array elements. By default no array access is allowed.

Since:

19.0

See Also:

Value.hasArrayElements()

targetTypeMapping

public <S,T> HostAccess.Builder targetTypeMapping(Class<S> sourceType,
                                                  Class<T> targetType,
                                                  Predicate<S> accepts,
                                                  Function<S,T> converter)

Adds a custom source to target type mapping for Java host calls, host field assignments and explicit value conversions. The source type specifies the static source type for the conversion. The target type specifies the exact and static target type of the mapping. Sub or base target types won't trigger the mapping. Custom target type mappings always have precedence over default mappings specified in Value.as(Class), therefore allow to customize their behavior. The provided converter takes a value of the source type and converts it to the target type. If the mapping is only conditionally applicable then an accepts predicate may be specified. If the mapping is applicable for all source values with the specified source type then a null accepts predicate should be specified. The converter may throw a ClassCastException if the mapping is not applicable. It is recommended to return false in the accepts predicate if the mapping is not applicable instead of throwing an exception. Implementing the accepts predicate instead of throwing an exception also allows the implementation to perform better overload selection when a method with multiple overloads is invoked.

All type mappings are applied recursively to generic types. A type mapping with the target type String.class will also be applied to the elements of a List mapping. This works for lists, maps, arrays and varargs parameters.

The source type uses the semantics of Value.as(Class) to convert to the source value. Custom type mappings are not applied there. If the source type is not applicable to a value then the mapping will not be applied. For conversions that may accept any value the Value should be used as source type.

Multiple mappings may be added for a source or target class. Multiple mappings are applied in the order they were added. The first mapping that accepts the source value will be used. Custom target type mappings all use the same precedence when an overloaded method is selected. This means that if two methods with a custom target type mapping are applicable for a set of arguments, an IllegalArgumentException is thrown at runtime.

Primitive boxed target types will be applied to the primitive and boxed values. It is therefore enough to specify a target mapping to Integer to also map to the target type int.class. Primitive target types can not be used as target types. They throw an IllegalArgumentException if used.

If the converter function or the accepts predicate calls Value.as(Class) recursively then custom target mappings are applied. Special care must be taken in order to not trigger stack overflow errors. It is recommended to use a restricted source type instead of Value.as(Class) where possible. It is strongly discouraged that accept predicates or converter cause any side-effects or escape values for permanent storage.

Usage example:

 public static class MyClass {

     @HostAccess.Export
     public void json(JsonObject c) {
     }

     @HostAccess.Export
     public String intToString(String c) {
         return c;
     }
 }

 public static class JsonObject {
     JsonObject(Value v) {
     }
 }

 public static void main(String[] args) {
     HostAccess.Builder builder = HostAccess.newBuilder();
     builder.allowAccessAnnotatedBy(HostAccess.Export.class);
     builder.targetTypeMapping(Value.class, JsonObject.class,
                     (v) -> v.hasMembers() || v.hasArrayElements(),
                     (v) -> new JsonObject(v)).build();

     builder.targetTypeMapping(Integer.class, String.class, null,
                     (v) -> v.toString());

     HostAccess access = builder.build();
     try (Context c = Context.newBuilder().allowHostAccess(access).build()) {
         c.getBindings("js").putMember("javaObject", new MyClass());
         c.eval("js", "javaObject.json({})"); // works!
         c.eval("js", "javaObject.json([])"); // works!
         try {
             c.eval("js", "javaObject.json(42)"); // fails!
         } catch (PolyglotException e) {
         }

         c.eval("js", "javaObject.intToString(42)"); // returns "42"
     }
 }
 

Parameters:

sourceType - the static source type to convert from with this mapping. The source type must be applicable for a mapping to be accepted.

targetType - the exact and static target type to convert to with this mapping.

accepts - the predicate to check whether a mapping is applicable. Returns true if the mapping is applicable else false. If set to null then all values of a given source type are applicable.

converter - a function that produces the converted value of the mapping. May return null. May throw ClassCastException if the source value is not convertible.

Throws:

IllegalArgumentException - for primitive target types.

Since:

19.0

build

public HostAccess build()

Creates an instance of the custom host access configuration.

Since:

19.0