0
# GraalVM Polyglot API
1

2
GraalVM Polyglot API enables embedding and interoperating with multiple programming languages within a single runtime environment. It provides comprehensive polyglot execution capabilities, host-guest interoperability, and fine-grained security controls for multi-language applications.
3

4
## Package Information
5

6
- **Package Name**: org.graalvm.polyglot
7
- **Package Type**: Maven
8
- **Language**: Java
9
- **Version**: 23.1.5
10
- **Installation**: `org.graalvm.polyglot:graalvm-sdk:23.1.5`
11

12
## Core Imports
13

14
```java { .api }
15
import org.graalvm.polyglot.Context;
16
import org.graalvm.polyglot.Engine;
17
import org.graalvm.polyglot.Value;
18
import org.graalvm.polyglot.Source;
19
import org.graalvm.polyglot.HostAccess;
20
import org.graalvm.polyglot.PolyglotAccess;
21
import org.graalvm.polyglot.SandboxPolicy;
22
```
23

24
## Basic Usage
25

26
```java
27
// Create context for multiple languages
28
try (Context context = Context.create("js", "python")) {
29
    // Evaluate JavaScript code
30
    Value result = context.eval("js", "6 * 7");
31
    System.out.println(result.asInt()); // 42
32
    
33
    // Host-guest interoperability
34
    Value bindings = context.getBindings("js");
35
    bindings.putMember("greeting", "Hello from Java!");
36
    
37
    context.eval("js", "console.log(greeting + ' Welcome to polyglot programming!')");
38
}
39
```
40

41
## Architecture
42

43
The GraalVM Polyglot API is organized around these core components:
44

45
- **Context**: Execution environment for guest languages with isolation and security
46
- **Engine**: Shared runtime that manages multiple contexts and languages
47
- **Value**: Language-agnostic wrapper for all polyglot values and operations
48
- **Source**: Represents source code with language and metadata information
49
- **Access Policies**: Fine-grained control over host access, polyglot interaction, and I/O
50

51
## Capabilities
52

53
### Context and Engine Management
54

55
Core lifecycle management for polyglot execution environments.
56

57
```java { .api }
58
// Context creation and configuration
59
public static Context create(String... permittedLanguages);
60
public static Context.Builder newBuilder(String... permittedLanguages);
61

62
// Engine creation and sharing
63
public static Engine create();
64
public static Engine create(String... permittedLanguages);
65
public static Engine.Builder newBuilder(String... permittedLanguages);
66

67
// Resource management
68
public void close();
69
public void close(boolean cancelIfExecuting);
70
```
71

72
[Context and Engine Management](./context-management.md)
73

74
### Language Execution and Source Parsing
75

76
Evaluation and parsing of source code across different programming languages.
77

78
```java { .api }
79
// Source code evaluation
80
public Value eval(Source source);
81
public Value eval(String languageId, CharSequence source);
82

83
// Source parsing without execution
84
public Value parse(Source source);
85
public Value parse(String languageId, CharSequence source);
86

87
// Source creation
88
public static Source create(String language, CharSequence source);
89
public static Source.Builder newBuilder(String language, CharSequence characters, String name);
90
```
91

92
[Language Execution and Parsing](./language-execution.md)
93

94
### Value Types and Host-Guest Interoperability
95

96
Language-agnostic value operations and seamless data exchange between host and guest languages.
97

98
```java { .api }
99
// Type checking and conversion
100
public boolean isNull();
101
public boolean isNumber();
102
public boolean isString();
103
public String asString();
104
public int asInt();
105
public double asDouble();
106
public <T> T as(Class<T> targetType);
107

108
// Container operations
109
public boolean hasArrayElements();
110
public Value getArrayElement(long index);
111
public boolean hasMembers();
112
public Value getMember(String identifier);
113

114
// Function execution
115
public boolean canExecute();
116
public Value execute(Object... arguments);
117
```
118

119
[Value Types and Host-Guest Interoperability](./value-interop.md)
120

121
### Proxy System for Custom Objects
122

123
Proxy interfaces enabling host objects to mimic guest language objects with custom behavior.
124

125
```java { .api }
126
// Base proxy interface
127
public interface Proxy {}
128

129
// Object-like behavior
130
public interface ProxyObject extends Proxy {
131
    Object getMember(String key);
132
    void putMember(String key, Value value);
133
    Object getMemberKeys();
134
}
135

136
// Array-like behavior
137
public interface ProxyArray extends ProxyIterable {
138
    Object get(long index);
139
    void set(long index, Value value);
140
    long getSize();
141
}
142

143
// Function-like behavior
144
public interface ProxyExecutable extends Proxy {
145
    Object execute(Value... arguments);
146
}
147
```
148

149
[Proxy System for Custom Objects](./proxy-system.md)
150

151
### Security and Access Control
152

153
Comprehensive security policies for controlling host access, polyglot evaluation, and sandboxing.
154

155
```java { .api }
156
// Host access policies
157
public static final HostAccess EXPLICIT;    // @Export annotation required
158
public static final HostAccess ALL;         // Full unrestricted access
159
public static final HostAccess CONSTRAINED; // Limited access for sandboxing
160
public static final HostAccess UNTRUSTED;   // Strict restrictions
161

162
// Polyglot access control
163
public static final PolyglotAccess ALL;  // Full cross-language access
164
public static final PolyglotAccess NONE; // No cross-language access
165

166
// Sandbox security levels
167
public enum SandboxPolicy {
168
    TRUSTED,     // No restrictions
169
    CONSTRAINED, // Basic restrictions
170
    ISOLATED,    // Enhanced isolation
171
    UNTRUSTED    // Maximum restrictions
172
}
173
```
174

175
[Security and Access Control](./security-access.md)
176

177
### I/O and File System Virtualization
178

179
Virtual file system abstraction and I/O access control for polyglot contexts.
180

181
```java { .api }
182
// I/O access policies
183
public static final IOAccess ALL;  // Full I/O access
184
public static final IOAccess NONE; // No I/O access
185

186
// File system operations
187
public interface FileSystem {
188
    Path parsePath(String path);
189
    void checkAccess(Path path, Set<? extends AccessMode> modes, LinkOption... linkOptions);
190
    SeekableByteChannel newByteChannel(Path path, Set<? extends OpenOption> options, FileAttribute<?>... attrs);
191
    DirectoryStream<Path> newDirectoryStream(Path dir, DirectoryStream.Filter<? super Path> filter);
192
}
193

194
// Byte sequence operations
195
public interface ByteSequence {
196
    int length();
197
    byte byteAt(int index);
198
    byte[] toByteArray();
199
}
200
```
201

202
[I/O and File System Virtualization](./io-filesystem.md)
203

204
### Execution Monitoring and Resource Management
205

206
Performance monitoring, execution tracking, and resource consumption limits.
207

208
```java { .api }
209
// Execution monitoring
210
public final class ExecutionListener implements AutoCloseable {
211
    public void onEnter(Consumer<ExecutionEvent> listener);
212
    public void onReturn(Consumer<ExecutionEvent> listener);
213
    public void attach(Engine engine);
214
    public void attach(Context context);
215
}
216

217
// Resource limits
218
public final class ResourceLimits {
219
    public static ResourceLimits.Builder newBuilder();
220
}
221

222
// Exception handling
223
public final class PolyglotException extends RuntimeException {
224
    public boolean isHostException();
225
    public boolean isGuestException();
226
    public Value getGuestObject();
227
    public SourceSection getSourceLocation();
228
}
229
```
230

231
[Execution Monitoring and Resource Management](./monitoring-management.md)
232

233
## Common Types
234

235
```java { .api }
236
// Language metadata
237
public final class Language {
238
    public String getId();
239
    public String getName();
240
    public Set<String> getMimeTypes();
241
    public boolean isInteractive();
242
}
243

244
// Instrument metadata
245
public final class Instrument {
246
    public String getId();
247
    public String getName();
248
    public String getVersion();
249
    public <T> T lookup(Class<T> type);
250
}
251

252
// Source location information
253
public final class SourceSection {
254
    public Source getSource();
255
    public int getStartLine();
256
    public int getEndLine();
257
    public int getStartColumn();
258
    public int getEndColumn();
259
    public CharSequence getCharacters();
260
}
261

262
// Type-safe generic conversion
263
public abstract class TypeLiteral<T> {
264
    public final Type getType();
265
    public final Class<T> getRawType();
266
}
267
```