Class HostAccess

java.lang.Object

org.graalvm.polyglot.HostAccess

public final class HostAccess
extends Object

Represents the host access policy of a polyglot context. The host access policy specifies which methods and fields are accessible to the guest application, whenever Java host objects are accessed.

There are three predefined instances of host access policies:

• EXPLICIT - Java host methods or fields, must be public and be annotated with @Export to make them accessible to the guest language.
• SCOPED - Java host methods or fields, must be public and be annotated with @Export to make them accessible to the guest language. Guest-to-host callback parameter validity is scoped to the duration of the callback by default.
• NONE - Does not allow any access to methods or fields of host objects. Java host objects may still be passed into a context, but they cannot be accessed.
• ALL - Does allow full unrestricted access to public methods or fields of host objects. Note that this policy allows unrestricted access to reflection. It is highly discouraged from using this policy in environments where the guest application is not fully trusted.
• CONSTRAINED host access policy suitable for a context with CONSTRAINED sandbox policy.
• ISOLATED host access policy suitable for a context with ISOLATED sandbox policy.
• UNTRUSTED host access policy suitable for a context with UNTRUSTED sandbox policy.

Custom host access policies can be created using newBuilder(). The builder allows to specify a custom export annotation and allowed and denied methods or fields.

Since:

19.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	HostAccess.Builder	Builder to create a custom host access policy.
static @interface	HostAccess.DisableMethodScoping	If SCOPED is used, placing this annotation on an exported host function excludes it from parameter scoping, i.e.
static @interface	HostAccess.Export	Annotation used by the predefined EXPLICIT access policy to mark public constructors, methods and fields in public classes that should be accessible by the guest application.
static @interface	HostAccess.Implementable	Allows guest language to implement a Java type.
static enum	HostAccess.MutableTargetMapping	List of default host object mappings of mutable target types available in Value.as(Class).
static enum	HostAccess.TargetMappingPrecedence	Represents the precedence of a target type mapping.

Field Summary

Fields

Modifier and Type	Field	Description
static final HostAccess	ALL	Predefined host access policy that allows full unrestricted access to public methods or fields of public host classes.
static final HostAccess	CONSTRAINED	Predefined host access policy used by Context with a SandboxPolicy.CONSTRAINED sandbox policy when the host access policy is not explicitly specified by the embedder.
static final HostAccess	EXPLICIT	Predefined host access policy that allows access to public host methods or fields that were annotated with @Export and were declared in public class.
static final HostAccess	ISOLATED	Predefined host access policy used by Context with an SandboxPolicy.ISOLATED sandbox policy when the host access policy is not explicitly specified by the embedder.
static final HostAccess	NONE	Predefined host access policy that disallows any access to public host methods or fields.
static final HostAccess	SCOPED	Predefined host access policy that is the same as EXPLICIT and enables method scoping of callback parameter values on top.
static final HostAccess	UNTRUSTED	Predefined host access policy used by Context with an SandboxPolicy.UNTRUSTED sandbox policy when the host access policy is not explicitly specified by the embedder.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)
int	hashCode()
static HostAccess.Builder	newBuilder()	Creates a new builder that allows to create a custom host access policy.
static HostAccess.Builder	newBuilder(HostAccess conf)	Creates a new builder that allows to create a custom host access policy based of a preset configuration.
String	toString()

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Details

EXPLICIT

public static final HostAccess EXPLICIT

Predefined host access policy that allows access to public host methods or fields that were annotated with @Export and were declared in public class. This is the default configuration if Context.Builder.allowAllAccess(boolean) is false.

Equivalent of using the following builder configuration:

HostAccess.newBuilder().allowAccessAnnotatedBy(HostAccess.Export.class).
               allowImplementationsAnnotatedBy(HostAccess.Implementable.class).
               allowImplementationsAnnotatedBy(FunctionalInterface.class).
               .build();

Since:

19.0

SCOPED

public static final HostAccess SCOPED

Predefined host access policy that is the same as EXPLICIT and enables method scoping of callback parameter values on top. Methods that are annotated with HostAccess.DisableMethodScoping are exempt from scoping.

Equivalent of using the following builder configuration:

HostAccess.newBuilder().allowAccessAnnotatedBy(HostAccess.Export.class).
                allowImplementationsAnnotatedBy(HostAccess.Implementable.class).
                allowImplementationsAnnotatedBy(FunctionalInterface.class).
                methodScoping(true).
                disableMethodScopingAnnotatedBy(HostAccess.DisableMethodScoping.class)
                .build();

Since:

21.3

ALL

public static final HostAccess ALL

Predefined host access policy that allows full unrestricted access to public methods or fields of public host classes. Note that this policy allows unrestricted access to reflection. It is highly discouraged from using this policy in environments where the guest application is not fully trusted. This is the default configuration if Context.Builder.allowAllAccess(boolean) is true.

Equivalent of using the following builder configuration:

HostAccess.newBuilder()
          allowPublicAccess(true).
          allowAllImplementations(true).
          allowAllClassImplementations(true).
          allowArrayAccess(true).
          allowListAccess(true).
          allowBufferAccess(true).
          allowIterableAccess(true).
          allowIteratorAccess(true).
          allowMapAccess(true).
          allowAccessInheritance(true).
          .build();

Since:

19.0

NONE

public static final HostAccess NONE

Predefined host access policy that disallows any access to public host methods or fields.

Equivalent of using the following builder configuration:

HostAccess.newBuilder().build();

Since:

19.0

CONSTRAINED

public static final HostAccess CONSTRAINED

Predefined host access policy used by Context with a SandboxPolicy.CONSTRAINED sandbox policy when the host access policy is not explicitly specified by the embedder.

Equivalent of using the following builder configuration:

HostAccess.newBuilder().
          allowAccessAnnotatedBy(Export.class).
          allowImplementationsAnnotatedBy(Implementable.class).
          allowMutableTargetMappings().build();

Since:

23.0

ISOLATED

public static final HostAccess ISOLATED

Predefined host access policy used by Context with an SandboxPolicy.ISOLATED sandbox policy when the host access policy is not explicitly specified by the embedder.

Equivalent of using the following builder configuration:

HostAccess.newBuilder(CONSTRAINED).
          methodScoping(true).build();

Since:

23.0

UNTRUSTED

public static final HostAccess UNTRUSTED

Predefined host access policy used by Context with an SandboxPolicy.UNTRUSTED sandbox policy when the host access policy is not explicitly specified by the embedder.

Equivalent of using the following builder configuration:

HostAccess.newBuilder().
          allowAccessAnnotatedBy(Export.class).
          allowMutableTargetMappings().
          methodScoping(true).build();

Since:

23.0

Method Details

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

Since:

20.3

hashCode

public int hashCode()

Overrides:

hashCode in class Object

Since:

20.3

newBuilder

public static HostAccess.Builder newBuilder()

Creates a new builder that allows to create a custom host access policy. The builder configuration needs to be completed using the method.

Since:

19.0

newBuilder

public static HostAccess.Builder newBuilder(HostAccess conf)

Creates a new builder that allows to create a custom host access policy based of a preset configuration. The preset configuration is copied and used as a template for the returned buidler. The builder configuration needs to be completed using the method.

Since:

19.0

toString

public String toString()

Overrides:

toString in class Object

Since:

19.0