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	allowAccessInheritance(boolean inheritAccess) Allows the guest application to inherit access to allowed methods, i.e.
HostAccess.Builder	allowAllClassImplementations(boolean allow) Allow guest languages to implement (extend) any Java 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	allowBigIntegerNumberAccess(boolean bigIntegerNumberAccess) Allows the guest application to access BigInteger as a number.
HostAccess.Builder	allowBufferAccess(boolean bufferAccess) Allows the guest application to access ByteBuffers as values with buffer elements.
HostAccess.Builder	allowImplementations(Class<?> type) 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	allowIterableAccess(boolean iterableAccess) Allows the guest application to access iterables as values with iterators.
HostAccess.Builder	allowIteratorAccess(boolean iteratorAccess) Allows the guest application to access iterators as iterator values.
HostAccess.Builder	allowListAccess(boolean listAccess) Allows the guest application to access lists as values with array elements and iterators.
HostAccess.Builder	allowMapAccess(boolean mapAccess) Allows the guest application to access map as hash values.
HostAccess.Builder	allowMutableTargetMappings(HostAccess.MutableTargetMapping... mapping) Allows host object mappings of mutable target types, such as List, Map, Iterator and Iterable based on the HostAccess.MutableTargetMapping.
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.
HostAccess.Builder	disableMethodScoping(Executable e) Function parameters of the specified executable escape the executable's scope.
HostAccess.Builder	disableMethodScopingAnnotatedBy(Class<? extends Annotation> annotation) Function parameters of a method annotated with the specified annotation are not scoped.
HostAccess.Builder	methodScoping(boolean scopingDefault) Sets the default scoping of callback function parameters.
<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.
<S,T> HostAccess.Builder	targetTypeMapping(Class<S> sourceType, Class<T> targetType, Predicate<S> accepts, Function<S,T> converter, HostAccess.TargetMappingPrecedence precedence) 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, 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.

Note that implementations implicitly export all their methods, i.e., allowing implementations of a type implies allowing access its methods via its implementations, regardless of whether the methods have been explicitly exported.

Since:

19.0

See Also:

HostAccess.ALL, HostAccess.Builder.allowImplementations(Class), HostAccess.Builder.allowImplementationsAnnotatedBy(Class)

allowAllClassImplementations

public HostAccess.Builder allowAllClassImplementations(boolean allow)

Allow guest languages to implement (extend) any Java class. Note that the default host type mappings and Value.as(Class) only implement abstract classes.

Note that implementations implicitly export all their methods, i.e., allowing implementations of a type implies allowing access its methods via its implementations, regardless of whether the methods have been explicitly exported.

Since:

20.3.0

See Also:

HostAccess.ALL, HostAccess.Builder.allowImplementations(Class), HostAccess.Builder.allowImplementationsAnnotatedBy(Class), HostAccess.Builder.allowAllImplementations(boolean)

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. Applies to interfaces and classes.

Note that implementations implicitly export all their methods, i.e., allowing implementations of a type implies allowing access its methods via its implementations, regardless of whether the methods have been explicitly exported.

Since:

19.0

See Also:

HostAccess.Implementable, HostAccess.Builder.allowImplementations(Class), Value.as(Class)

allowImplementations

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

Allow implementations of this type by the guest language.

Note that implementations implicitly export all their methods, i.e., allowing implementations of a type implies allowing access its methods via its implementations, regardless of whether the methods have been explicitly exported.

Parameters:

type - an interface that may be implemented or a class that may be extended.

Since:

19.0

See Also:

HostAccess.Builder.allowImplementationsAnnotatedBy(Class), Value.as(Class)

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 and iterators. By default no array access is allowed. Allowing list access implies also allowing of iterables and iterators.

Since:

19.0

See Also:

Value.hasArrayElements(), Value.hasIterator()

allowIterableAccess

public HostAccess.Builder allowIterableAccess(boolean iterableAccess)

Allows the guest application to access iterables as values with iterators. By default no iterable access is allowed. Allowing iterable access implies also allowing of iterators.

Since:

21.1

See Also:

Value.hasIterator()

allowIteratorAccess

public HostAccess.Builder allowIteratorAccess(boolean iteratorAccess)

Allows the guest application to access iterators as iterator values. By default no iterator access is allowed.

Since:

21.1

See Also:

Value.isIterator(), Value.hasIteratorNextElement(), Value.getIteratorNextElement()

allowMapAccess

public HostAccess.Builder allowMapAccess(boolean mapAccess)

Allows the guest application to access map as hash values. By default no map access is allowed. Allowing map access implies also allowing of iterators.

Since:

21.1

See Also:

Value.hasHashEntries()

allowBigIntegerNumberAccess

public HostAccess.Builder allowBigIntegerNumberAccess(boolean bigIntegerNumberAccess)

Allows the guest application to access BigInteger as a number. By default BigInteger number access is allowed.

Since:

23.0

See Also:

Value.isNumber()

allowBufferAccess

public HostAccess.Builder allowBufferAccess(boolean bufferAccess)

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

Since:

21.1

See Also:

Value.hasBufferElements()

allowAccessInheritance

public HostAccess.Builder allowAccessInheritance(boolean inheritAccess)

Allows the guest application to inherit access to allowed methods, i.e. implementations of allowed abstract and interface methods and overrides of allowed concrete methods. If access inheritance is disabled, all method implementations need to be explicitly allowed (either by an annotation or using reflection) to be available. Consequently, attempting to allow abstract methods has no effect in this access mode. Rationale: Requiring explicit vetting of all method implementations prevents unintentional exporting of newly added or overridden methods. When a user annotates an abstract (or concrete) method as exported, they might still know what that means when they write the code and know of all its implementations; but they might forget it later and other contributors to the codebase might not be aware of what is exported through an interface or superclass. So when someone introduces a new implementation or overrides the method in a subclass, perhaps a few levels down, they could be accidentally exporting it to the guest application.

Since:

22.2

See Also:

HostAccess.Builder.allowAccessAnnotatedBy(Class), HostAccess.Builder.allowAccess(Executable)

allowMutableTargetMappings

public HostAccess.Builder allowMutableTargetMappings(HostAccess.MutableTargetMapping... mapping)

Allows host object mappings of mutable target types, such as List, Map, Iterator and Iterable based on the HostAccess.MutableTargetMapping. Mapping guest objects to well-known host object types such as Map is convenient on one hand. On the other hand it can lead to bugs as the guest code is free to provide an arbitrary backing implementation of such objects, which may not behave as expected of a Map.

Since:

23.0

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. Method is equivalent to calling the targetTypeMapping method with precedence HostAccess.TargetMappingPrecedence.HIGH.

Since:

19.0

targetTypeMapping

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

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, grouped by the priority where the highest priority group is applied first. See Value.as(Class) for a detailed ordered list of the conversion order used. The first mapping that accepts the source value will be used. If the default priority is used then all custom target type mappings 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. Using a non-default priority for the mapping allows to configure whether the method will be prioritized or deprioritized depending on the precedence.

For example take a configured target mapping from String to int and two overloaded methods that takes an int or a String parameter. If this method is invoked with a String value then there are three possible outcomes depending on the precedence that was used for the custom mapping:

• HostAccess.TargetMappingPrecedence.HIGHEST: The int method overload will be selected and invoked as the target mapping has a higher precedence than default.
• HostAccess.TargetMappingPrecedence.HIGH: The execution fails with an error as all overloads have equivalent precedence.
• HostAccess.TargetMappingPrecedence.LOW or HostAccess.TargetMappingPrecedence.LOWEST: The String method overload will be selected and invoked as the target mapping has a lower precedence than default.
• In this example the outcome of low and lowest are equivalent. There are differences between low and lowest. See HostAccess.TargetMappingPrecedence for details.

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.

precedence - the precedence of the defined mapping which influences conversion order and precedence with default mappings and other target type mappings.

Throws:

IllegalArgumentException - for primitive target types.

Since:

20.3

methodScoping

public HostAccess.Builder methodScoping(boolean scopingDefault)

Sets the default scoping of callback function parameters. Parameters escape from the scope of a function, if a reference to them is kept after the function returns. To use a value beyond the method scope Value.pin() may be used.

Since:

21.3

See Also:

Value.pin()

disableMethodScopingAnnotatedBy

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

Function parameters of a method annotated with the specified annotation are not scoped.

Since:

21.3

disableMethodScoping

public HostAccess.Builder disableMethodScoping(Executable e)

Function parameters of the specified executable escape the executable's scope.

Since:

21.3

build

public HostAccess build()

Creates an instance of the custom host access configuration.

Since:

19.0