0
# Polyglot Language Embedding
1

2
Comprehensive API for embedding and executing multiple programming languages within Java applications, with full type safety, sandboxing, and resource management.
3

4
## Capabilities
5

6
### Context Management
7

8
Main entry point for polyglot embedding providing isolated execution environments with configurable security and resource limits.
9

10
```java { .api }
11
/**
12
 * Creates and manages a polyglot execution context for running guest languages
13
 */
14
public final class Context implements AutoCloseable {
15
    /** Create context with default settings for specified languages */
16
    public static Context create(String... permittedLanguages);
17
    
18
    /** Create builder for advanced context configuration */
19
    public static Context.Builder newBuilder(String... permittedLanguages);
20
    
21
    /** Evaluate source code in specified language */
22
    public Value eval(String languageId, CharSequence source);
23
    
24
    /** Evaluate a Source object */
25
    public Value eval(Source source);
26
    
27
    /** Get global bindings for a language */
28
    public Value getBindings(String languageId);
29
    
30
    /** Initialize specified language without executing code */
31
    public void initialize(String languageId);
32
    
33
    /** Close context and release all resources */
34
    public void close();
35
    
36
    /** Get current execution context */
37
    public static Context getCurrent();
38
    
39
    /** Enter this context for current thread */
40
    public void enter();
41
    
42
    /** Leave this context for current thread */
43
    public void leave();
44
}
45

46
/**
47
 * Builder for configuring Context instances with security and resource settings
48
 */
49
public static final class Context.Builder {
50
    /** Allow access to host classes and objects */
51
    public Context.Builder allowHostAccess(HostAccess config);
52
    
53
    /** Configure cross-language access */
54
    public Context.Builder allowPolyglotAccess(PolyglotAccess config);
55
    
56
    /** Allow native access for languages that support it */
57
    public Context.Builder allowNativeAccess(boolean enabled);
58
    
59
    /** Allow creating threads */
60
    public Context.Builder allowCreateThread(boolean enabled);
61
    
62
    /** Allow host I/O operations */
63
    public Context.Builder allowIO(boolean enabled);
64
    
65
    /** Set environment access policy */
66
    public Context.Builder allowEnvironmentAccess(EnvironmentAccess config);
67
    
68
    /** Configure custom file system */
69
    public Context.Builder fileSystem(FileSystem fileSystem);
70
    
71
    /** Set resource limits */
72
    public Context.Builder resourceLimits(ResourceLimits limits);
73
    
74
    /** Set sandbox policy */
75
    public Context.Builder sandbox(SandboxPolicy policy);
76
    
77
    /** Build the configured context */
78
    public Context build();
79
}
80
```
81

82
**Usage Examples:**
83

84
```java
85
// Basic context usage
86
try (Context context = Context.create("js", "python")) {
87
    Value result = context.eval("js", "Math.max(42, 100)");
88
    System.out.println(result.asInt()); // 100
89
}
90

91
// Advanced configuration
92
Context context = Context.newBuilder("js")
93
    .allowHostAccess(HostAccess.ALL)
94
    .allowPolyglotAccess(PolyglotAccess.ALL)
95
    .sandbox(SandboxPolicy.CONSTRAINED)
96
    .build();
97
```
98

99
### Value Handling
100

101
Represents values from guest languages with automatic type conversion and safe access to language-specific operations.
102

103
```java { .api }
104
/**
105
 * Represents a polyglot value that can be converted between language representations
106
 */
107
public final class Value {
108
    /** Convert to Java type with automatic conversion */
109
    public <T> T as(Class<T> targetType);
110
    
111
    /** Convert to primitive boolean */
112
    public boolean asBoolean();
113
    
114
    /** Convert to primitive int */
115
    public int asInt();
116
    
117
    /** Convert to primitive long */
118
    public long asLong();
119
    
120
    /** Convert to primitive float */
121
    public float asFloat();
122
    
123
    /** Convert to primitive double */
124
    public double asDouble();
125
    
126
    /** Convert to Java String */
127
    public String asString();
128
    
129
    /** Execute if this value is executable */
130
    public Value execute(Object... arguments);
131
    
132
    /** Instantiate if this value is instantiable */
133
    public Value newInstance(Object... arguments);
134
    
135
    /** Get member by key/index */
136
    public Value getMember(String key);
137
    
138
    /** Set member by key */
139
    public void putMember(String key, Object value);
140
    
141
    /** Check if member exists */
142
    public boolean hasMember(String key);
143
    
144
    /** Get all member keys */
145
    public Set<String> getMemberKeys();
146
    
147
    /** Get array element by index */
148
    public Value getArrayElement(long index);
149
    
150
    /** Set array element by index */
151
    public void setArrayElement(long index, Object value);
152
    
153
    /** Get array size */
154
    public long getArraySize();
155
    
156
    // Type checking methods
157
    public boolean isNull();
158
    public boolean isBoolean();
159
    public boolean isNumber();
160
    public boolean isString();
161
    public boolean canExecute();
162
    public boolean canInstantiate();
163
    public boolean hasMembers();
164
    public boolean hasArrayElements();
165
    public boolean isHostObject();
166
    public boolean isProxyObject();
167
}
168
```
169

170
**Usage Examples:**
171

172
```java
173
try (Context context = Context.create("js")) {
174
    // Function execution
175
    Value jsFunction = context.eval("js", "(x, y) => x + y");
176
    Value result = jsFunction.execute(5, 10);
177
    System.out.println(result.asInt()); // 15
178
    
179
    // Object member access
180
    Value jsObject = context.eval("js", "({name: 'Alice', age: 30})");
181
    System.out.println(jsObject.getMember("name").asString()); // Alice
182
    
183
    // Array operations
184
    Value jsArray = context.eval("js", "[1, 2, 3]");
185
    System.out.println(jsArray.getArraySize()); // 3
186
    System.out.println(jsArray.getArrayElement(1).asInt()); // 2
187
}
188
```
189

190
### Engine Management
191

192
Shared execution engine for contexts providing language and instrument discovery with centralized configuration.
193

194
```java { .api }
195
/**
196
 * Shared polyglot execution engine managing languages and instruments
197
 */
198
public final class Engine implements AutoCloseable {
199
    /** Create engine with default settings */
200
    public static Engine create();
201
    
202
    /** Create builder for engine configuration */
203
    public static Engine.Builder newBuilder();
204
    
205
    /** Get all available languages */
206
    public Map<String, Language> getLanguages();
207
    
208
    /** Get all available instruments */
209
    public Map<String, Instrument> getInstruments();
210
    
211
    /** Get engine configuration options */
212
    public OptionDescriptors getOptions();
213
    
214
    /** Get cached sources */
215
    public Set<Source> getCachedSources();
216
    
217
    /** Close engine and release resources */
218
    public void close();
219
    
220
    /** Get engine version */
221
    public String getVersion();
222
}
223

224
/**
225
 * Builder for configuring Engine instances
226
 */
227
public static final class Engine.Builder {
228
    /** Set option value */
229
    public <T> Engine.Builder option(String key, String value);
230
    
231
    /** Allow experimental options */
232
    public Engine.Builder allowExperimentalOptions(boolean enabled);
233
    
234
    /** Set error output stream */
235
    public Engine.Builder err(OutputStream err);
236
    
237
    /** Set standard output stream */
238
    public Engine.Builder out(OutputStream out);
239
    
240
    /** Set standard input stream */
241
    public Engine.Builder in(InputStream in);
242
    
243
    /** Build configured engine */
244
    public Engine build();
245
}
246
```
247

248
### Source Management
249

250
Represents source code with metadata for caching, debugging, and error reporting.
251

252
```java { .api }
253
/**
254
 * Represents source code with metadata and caching support
255
 */
256
public final class Source {
257
    /** Create source from string */
258
    public static Source create(String language, CharSequence characters);
259
    
260
    /** Create source from file */
261
    public static Source create(String language, File file) throws IOException;
262
    
263
    /** Create source from URL */
264
    public static Source create(String language, URL url) throws IOException;
265
    
266
    /** Create builder for advanced source configuration */
267
    public static Source.Builder newBuilder(String language, Reader source, String name);
268
    
269
    /** Get source language ID */
270
    public String getLanguage();
271
    
272
    /** Get source name for debugging */
273
    public String getName();
274
    
275
    /** Get source characters */
276
    public CharSequence getCharacters();
277
    
278
    /** Get source MIME type */
279
    public String getMimeType();
280
    
281
    /** Get source URI if available */
282
    public URI getURI();
283
    
284
    /** Check if source is interactive */
285
    public boolean isInteractive();
286
    
287
    /** Check if source has bytes */
288
    public boolean hasBytes();
289
    
290
    /** Check if source has characters */
291
    public boolean hasCharacters();
292
}
293

294
/**
295
 * Builder for configuring Source instances
296
 */
297
public static final class Source.Builder {
298
    /** Set MIME type */
299
    public Source.Builder mimeType(String mimeType);
300
    
301
    /** Mark as interactive source */
302
    public Source.Builder interactive(boolean interactive);
303
    
304
    /** Set source URI */
305
    public Source.Builder uri(URI uri);
306
    
307
    /** Enable caching */
308
    public Source.Builder cached(boolean cached);
309
    
310
    /** Build configured source */
311
    public Source build() throws IOException;
312
}
313
```
314

315
### Language and Instrument Metadata
316

317
Information about available languages and development tools with version and option details.
318

319
```java { .api }
320
/**
321
 * Metadata about an available polyglot language
322
 */
323
public final class Language {
324
    /** Get language identifier */
325
    public String getId();
326
    
327
    /** Get human-readable language name */
328
    public String getName();
329
    
330
    /** Get language implementation name */
331
    public String getImplementationName();
332
    
333
    /** Get language version */
334
    public String getVersion();
335
    
336
    /** Get default MIME type */
337
    public String getDefaultMimeType();
338
    
339
    /** Get all supported MIME types */
340
    public Set<String> getMimeTypes();
341
    
342
    /** Get language configuration options */
343
    public OptionDescriptors getOptions();
344
    
345
    /** Check if language is interactive */
346
    public boolean isInteractive();
347
}
348

349
/**
350
 * Metadata about an available development instrument/tool
351
 */
352
public final class Instrument {
353
    /** Get instrument identifier */
354
    public String getId();
355
    
356
    /** Get human-readable instrument name */
357
    public String getName();
358
    
359
    /** Get instrument version */
360
    public String getVersion();
361
    
362
    /** Get instrument configuration options */
363
    public OptionDescriptors getOptions();
364
}
365
```
366

367
### Exception Handling
368

369
Specialized exception type for polyglot execution errors with stack trace and guest object access.
370

371
```java { .api }
372
/**
373
 * Exception thrown during polyglot execution with guest language details
374
 */
375
public final class PolyglotException extends RuntimeException {
376
    /** Check if exception originated from guest language */
377
    public boolean isGuestException();
378
    
379
    /** Check if this is a host exception */
380
    public boolean isHostException();
381
    
382
    /** Get guest exception object if available */
383
    public Value getGuestObject();
384
    
385
    /** Get polyglot stack trace with all languages */
386
    public Iterable<StackFrame> getPolyglotStackTrace();
387
    
388
    /** Check if exception indicates syntax error */
389
    public boolean isSyntaxError();
390
    
391
    /** Check if execution was cancelled */
392
    public boolean isCancelled();
393
    
394
    /** Check if exception was caused by exit */
395
    public boolean isExit();
396
    
397
    /** Get exit status if this is an exit exception */
398
    public int getExitStatus();
399
    
400
    /** Check if this indicates resource exhaustion */
401
    public boolean isResourceExhausted();
402
    
403
    /** Check if this is an interrupt */
404
    public boolean isInterrupted();
405
}
406

407
/**
408
 * Stack frame from polyglot stack trace
409
 */
410
public static final class StackFrame {
411
    /** Get source location if available */
412
    public SourceSection getSourceLocation();
413
    
414
    /** Get root name (function/method name) */
415
    public String getRootName();
416
    
417
    /** Get language information */
418
    public Language getLanguage();
419
    
420
    /** Check if this is a guest language frame */
421
    public boolean isGuestFrame();
422
    
423
    /** Check if this is a host frame */
424
    public boolean isHostFrame();
425
}
426
```
427

428
## Types
429

430
```java { .api }
431
// Access configuration enums
432
public enum SandboxPolicy {
433
    TRUSTED,        // Full system access
434
    CONSTRAINED,    // Limited system access
435
    ISOLATED,       // No system access
436
    UNTRUSTED       // Strictest isolation
437
}
438

439
// Host access configuration
440
public final class HostAccess {
441
    public static final HostAccess NONE;        // No host access
442
    public static final HostAccess ALL;         // Full host access
443
    public static final HostAccess EXPLICIT;    // Explicit annotations only
444
    
445
    public static HostAccess.Builder newBuilder();
446
}
447

448
// Cross-language access configuration
449
public final class PolyglotAccess {
450
    public static final PolyglotAccess NONE;    // No cross-language access
451
    public static final PolyglotAccess ALL;     // Full cross-language access
452
    
453
    public static PolyglotAccess.Builder newBuilder();
454
}
455

456
// Environment access configuration
457
public final class EnvironmentAccess {
458
    public static final EnvironmentAccess NONE;     // No environment access
459
    public static final EnvironmentAccess INHERIT;  // Inherit from host
460
}
461

462
// Resource consumption limits
463
public final class ResourceLimits {
464
    public static ResourceLimits.Builder newBuilder();
465
}
466
```