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

All Methods Instance Methods Concrete Methods
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`	`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`	`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`	`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`.
`<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, 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.
    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. 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. 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
  - build
```
public HostAccess build()
```
    Creates an instance of the custom host access configuration.
    
    Since:
    
    19.0

Class HostAccess.Builder

Method Summary

Methods inherited from class java.lang.Object

Method Detail

allowAccessAnnotatedBy

allowPublicAccess

allowAccess

allowAccess

denyAccess

denyAccess

allowAllImplementations

allowAllClassImplementations

allowImplementationsAnnotatedBy

allowImplementations

allowArrayAccess

allowListAccess

targetTypeMapping

targetTypeMapping

build