0
# GraalVM SDK
1

2
The GraalVM SDK is a comprehensive meta-package that provides core APIs for building high-performance, multi-language applications with native compilation capabilities. It aggregates seven specialized modules covering polyglot language embedding, native AOT compilation, memory-efficient collections, and low-level system integration.
3

4
## Package Information
5

6
- **Package Name**: graal-sdk
7
- **Group ID**: org.graalvm.sdk
8
- **Artifact ID**: graal-sdk
9
- **Package Type**: maven
10
- **Language**: Java
11
- **Installation**: Add to Maven dependencies with `<groupId>org.graalvm.sdk</groupId>` and `<artifactId>graal-sdk</artifactId>`
12

13
## Core Imports
14

15
All functionality is accessed through standard Java imports from the aggregated modules:
16

17
```java
18
// Polyglot language embedding
19
import org.graalvm.polyglot.*;
20
import org.graalvm.polyglot.proxy.*;
21
import org.graalvm.polyglot.io.*;
22

23
// Native Image AOT compilation
24
import org.graalvm.nativeimage.*;
25
import org.graalvm.nativeimage.hosted.*;
26
import org.graalvm.nativeimage.c.function.*;
27
import org.graalvm.nativeimage.c.type.*;
28

29
// Memory-efficient collections
30
import org.graalvm.collections.*;
31

32
// Low-level memory access
33
import org.graalvm.word.*;
34

35
// Installation and configuration
36
import org.graalvm.home.*;
37
import org.graalvm.options.*;
38

39
// JNI utilities for native integration
40
import org.graalvm.jniutils.*;
41

42
// Native bridge for cross-runtime communication
43
import org.graalvm.nativebridge.*;
44

45
// Native Image substitutions (compatibility only)
46
import com.oracle.svm.core.annotate.*;
47
```
48

49
## Basic Usage
50

51
```java
52
import org.graalvm.polyglot.*;
53
import org.graalvm.collections.*;
54
import org.graalvm.word.*;
55

56
public class GraalVMExample {
57
    public static void main(String[] args) {
58
        // Polyglot language embedding
59
        try (Context context = Context.create()) {
60
            // Execute JavaScript code
61
            Value result = context.eval("js", "Math.max(42, 100)");
62
            System.out.println("JavaScript result: " + result.asInt());
63
            
64
            // Execute Python code (if available)
65
            Value pyResult = context.eval("python", "len([1, 2, 3])");
66
            System.out.println("Python result: " + pyResult.asInt());
67
        }
68
        
69
        // Use memory-efficient collections
70
        EconomicMap<String, Integer> map = EconomicMap.create();
71
        map.put("count", 42);
72
        System.out.println("Map value: " + map.get("count"));
73
        
74
        // Low-level word operations (in native image context)
75
        UnsignedWord size = WordFactory.unsigned(1024);
76
        UnsignedWord doubled = size.multiply(2);
77
        System.out.println("Doubled size: " + doubled.rawValue());
78
    }
79
}
80
```
81

82
## Architecture
83

84
The GraalVM SDK is built around several key architectural components:
85

86
- **Meta-Package Design**: Aggregates seven specialized modules while maintaining backward compatibility through a deprecated `org.graalvm.sdk` package
87
- **Polyglot Engine**: Shared execution context for multiple programming languages with sandboxing and resource limits  
88
- **Native Compilation**: AOT compilation system for Java applications with C interoperability and custom substitutions
89
- **Memory Management**: Custom collection implementations optimized for native images and low GC pressure
90
- **Type Safety**: Low-level memory access through type-safe word interfaces that compile to machine code
91
- **Plugin Architecture**: Extensible feature system for customizing native image generation
92
- **Configuration System**: Unified option management across languages and tools
93

94
## Capabilities
95

96
### Polyglot Language Embedding
97

98
Execute JavaScript, Python, Ruby, WebAssembly, and other languages from Java applications with full type safety, sandboxing support, and I/O virtualization.
99

100
```java { .api }
101
// Core polyglot context management
102
public final class Context implements AutoCloseable {
103
    public static Context create(String... permittedLanguages);
104
    public static Context.Builder newBuilder(String... permittedLanguages);
105
    public Value eval(String languageId, CharSequence source);
106
    public Value getBindings(String languageId);
107
    public void close();
108
}
109

110
public final class Value {
111
    public <T> T as(Class<T> targetType);
112
    public boolean asBoolean();
113
    public int asInt();
114
    public long asLong();
115
    public double asDouble();
116
    public String asString();
117
    public Value execute(Object... arguments);
118
    public Value getMember(String key);
119
    public boolean canExecute();
120
    public boolean hasMembers();
121
}
122

123
// I/O virtualization interfaces
124
public interface FileSystem {
125
    Path parsePath(String path);
126
    void checkAccess(Path path, Set<AccessMode> modes, LinkOption... linkOptions);
127
    SeekableByteChannel newByteChannel(Path path, Set<OpenOption> options, FileAttribute<?>... attrs);
128
}
129

130
public interface ProcessHandler {
131
    Process start(ProcessBuilder processBuilder);
132
    ProcessBuilder.Redirect redirect(ProcessBuilder.Redirect redirect);
133
}
134
```
135

136
[Polyglot Language Embedding](./polyglot.md)
137

138
### Native Image Compilation
139

140
APIs for AOT compilation of Java applications to native executables with C interoperability and runtime customization.
141

142
```java { .api }
143
// Core native image runtime information
144
public final class ImageInfo {
145
    public static boolean inImageCode();
146
    public static boolean inImageBuildtimeCode(); 
147
    public static boolean inImageRuntimeCode();
148
    public static boolean isExecutable();
149
    public static boolean isSharedLibrary();
150
}
151

152
// Singleton registry for native image
153
public final class ImageSingletons {
154
    public static <T> void add(Class<T> key, T value);
155
    public static <T> T lookup(Class<T> key);
156
    public static boolean contains(Class<?> key);
157
}
158

159
// Build-time customization
160
public interface Feature {
161
    void afterRegistration(AfterRegistrationAccess access);
162
    void beforeAnalysis(BeforeAnalysisAccess access);
163
    void duringAnalysis(DuringAnalysisAccess access);
164
    void afterAnalysis(AfterAnalysisAccess access);
165
}
166
```
167

168
[Native Image Compilation](./native-image.md)
169

170
### Memory-Efficient Collections
171

172
Dynamic data structures that automatically optimize representation based on size, ideal for native images and low-memory environments. Includes specialized concurrent data structures and object pools.
173

174
```java { .api }
175
// Memory-efficient map with dynamic representation
176
public interface EconomicMap<K, V> extends UnmodifiableEconomicMap<K, V> {
177
    static <K, V> EconomicMap<K, V> create();
178
    static <K, V> EconomicMap<K, V> create(Equivalence strategy);
179
    V put(K key, V value);
180
    V removeKey(K key);
181
    void clear();
182
    void putAll(EconomicMap<K, V> other);
183
}
184

185
// Memory-efficient set implementation  
186
public interface EconomicSet<E> extends UnmodifiableEconomicSet<E> {
187
    static <E> EconomicSet<E> create();
188
    static <E> EconomicSet<E> create(Equivalence strategy);
189
    boolean add(E element);
190
    boolean remove(E element);
191
    void clear();
192
}
193

194
// Thread-safe object pool for expensive resources
195
public final class LockFreePool<T> {
196
    static <T> LockFreePool<T> create(Supplier<T> factory);
197
    T get();
198
    void put(T object);
199
}
200

201
// Lock-free radix tree for fast string lookups
202
public final class LockFreePrefixTree {
203
    static LockFreePrefixTree create();
204
    void put(String key, Object value);
205
    Object get(String key);
206
    Set<String> getKeysWithPrefix(String prefix);
207
}
208
```
209

210
[Memory-Efficient Collections](./collections.md)
211

212
### Low-Level Memory Access
213

214
Type-safe APIs for machine-word-sized values and direct memory access, compiled to efficient native code.
215

216
```java { .api }
217
// Machine word-sized unsigned arithmetic
218
public interface UnsignedWord extends ComparableWord {
219
    UnsignedWord add(UnsignedWord val);
220
    UnsignedWord subtract(UnsignedWord val);
221
    UnsignedWord multiply(UnsignedWord val);
222
    UnsignedWord unsignedDivide(UnsignedWord val);
223
    UnsignedWord and(UnsignedWord val);
224
    UnsignedWord or(UnsignedWord val);
225
}
226

227
// Direct memory pointer access
228
public interface Pointer extends UnsignedWord, PointerBase {
229
    byte readByte(UnsignedWord offset);
230
    void writeByte(UnsignedWord offset, byte val);
231
    int readInt(UnsignedWord offset);
232
    void writeInt(UnsignedWord offset, int val);
233
}
234
```
235

236
[Low-Level Memory Access](./word.md)
237

238
### Installation and Configuration
239

240
APIs for discovering GraalVM installation paths, version information, and managing configuration options.
241

242
```java { .api }
243
// GraalVM installation discovery
244
public abstract class HomeFinder {
245
    public static HomeFinder getInstance();
246
    public abstract String getHomeFolder();
247
    public abstract Version getVersion();
248
    public abstract Map<String, String> getLanguageHomes();
249
    public abstract Map<String, String> getToolHomes();
250
}
251

252
// Type-safe option management
253
public final class OptionKey<T> {
254
    public T getValue(OptionValues values);
255
    public boolean hasBeenSet(OptionValues values);
256
}
257

258
public final class OptionDescriptor {
259
    public String getName();
260
    public OptionKey<?> getKey();
261
    public String getHelp();
262
    public OptionCategory getCategory();
263
}
264
```
265

266
[Installation and Configuration](./config.md)
267

268
### C Interoperability
269

270
Low-level APIs for C function calls and data type interoperability in native images.
271

272
```java { .api }
273
// C function pointer types
274
public interface CFunctionPointer extends CodePointer, RelocatedPointer {
275
}
276

277
// Typed C primitive pointers
278
public interface CIntPointer extends PointerBase {
279
    int read();
280
    int read(int index);
281
    void write(int value);
282
    void write(int index, int value);
283
}
284

285
// Generic C pointer operations
286
public interface CCharPointer extends PointerBase {
287
    byte read();
288
    void write(byte value);
289
    CCharPointer addressOf(int index);
290
}
291
```
292

293
[C Interoperability](./c-interop.md)
294

295
### JNI Utils
296

297
Simplified and safer JNI programming utilities with type-safe wrappers, automatic exception handling, and streamlined native method integration.
298

299
```java { .api }
300
// Core JNI utility functions
301
public final class JNI {
302
    public static <T> T NewLocalRef(T obj);
303
    public static void DeleteLocalRef(Object obj);
304
    public static <T> T NewGlobalRef(T obj);
305
    public static void DeleteGlobalRef(Object obj);
306
    public static Class<?> GetObjectClass(Object obj);
307
    public static boolean ExceptionCheck();
308
    public static void ExceptionClear();
309
}
310

311
// Scoped JNI method execution
312
public final class JNIMethodScope implements AutoCloseable {
313
    public static JNIMethodScope scope();
314
    public <T> T scope(Supplier<T> operation);
315
    public void scope(Runnable operation);
316
    public void close();
317
}
318

319
// Entry point generation annotation
320
@Target(ElementType.METHOD)
321
public @interface JNIEntryPoint {
322
    String name() default "";
323
    String signature() default "";
324
    boolean exceptionHandling() default true;
325
}
326
```
327

328
[JNI Utils](./jni-utils.md)
329

330
### Native Bridge
331

332
Communication APIs for bridging between different runtime environments with seamless data marshalling and cross-context method calls.
333

334
```java { .api }
335
// Bridge generation annotations
336
@Target(ElementType.TYPE)
337
public @interface GenerateHotSpotToNativeBridge {
338
    Class<?> value();
339
    String name() default "";
340
    Class<? extends MarshallerConfig> marshallerConfig() default DefaultMarshallerConfig.class;
341
}
342

343
// Object marshalling interfaces
344
public interface BinaryMarshaller<T> {
345
    byte[] marshal(T object);
346
    T unmarshal(byte[] data);
347
    int estimateSize(T object);
348
    boolean canMarshal(T object);
349
}
350

351
// Reference passing control
352
@Target({ElementType.PARAMETER, ElementType.METHOD, ElementType.TYPE})
353
public @interface ByRemoteReference {
354
    long timeout() default 30000L;
355
    boolean cache() default true;
356
}
357

358
// Isolate management
359
public static class NativeIsolateConfig {
360
    public final long maxHeapSize;
361
    public final long initialHeapSize;
362
    public final int stackSize;
363
    public final boolean debugMode;
364
    
365
    public static NativeIsolateConfig createDefault();
366
}
367
```
368

369
[Native Bridge](./native-bridge.md)
370

371
### Native Image Substitutions
372

373
Build-time class modification system for replacing methods and fields during native compilation (compatibility API).
374

375
```java { .api }
376
// Target class identification
377
@Target(ElementType.TYPE)
378
public @interface TargetClass {
379
    Class<?> value() default void.class;
380
    String className() default "";
381
}
382

383
// Method replacement
384
@Target(ElementType.METHOD)
385
public @interface Substitute {
386
    boolean polymorphicSignature() default false;
387
    boolean isStatic() default false;
388
}
389

390
// Field value recomputation
391
@Target(ElementType.FIELD)
392
public @interface RecomputeFieldValue {
393
    Kind kind();
394
    Class<?> declClass() default void.class;
395
    String name() default "";
396
    boolean isFinal() default true;
397
}
398
```
399

400
[Native Image Substitutions](./substitutions.md)
401

402
## Types
403

404
```java { .api }
405
// Polyglot types
406
public final class Engine implements AutoCloseable {
407
    public static Engine create();
408
    public Map<String, Language> getLanguages();
409
    public Map<String, Instrument> getInstruments();
410
    public OptionDescriptors getOptions();
411
}
412

413
public final class Source {
414
    public static Source create(String language, CharSequence characters);
415
    public static Source.Builder newBuilder(String language, Reader source, String name);
416
    public String getLanguage();
417
    public String getName();
418
    public CharSequence getCharacters();
419
}
420

421
public final class Language {
422
    public String getId();
423
    public String getName();
424
    public String getVersion();
425
    public Set<String> getMimeTypes();
426
    public OptionDescriptors getOptions();
427
}
428

429
public final class Instrument {
430
    public String getId();
431
    public String getName();
432
    public String getVersion();
433
    public OptionDescriptors getOptions();
434
}
435

436
// Collection comparison strategies
437
public abstract class Equivalence {
438
    public static final Equivalence DEFAULT;
439
    public static final Equivalence IDENTITY;
440
    public abstract boolean equals(Object a, Object b);
441
    public abstract int hashCode(Object o);
442
}
443

444
// Word factory for creating values
445
public final class WordFactory {
446
    public static UnsignedWord zero();
447
    public static <T extends PointerBase> T nullPointer();
448
    public static UnsignedWord unsigned(long val);
449
    public static SignedWord signed(long val);
450
    public static <T extends PointerBase> T pointer(long val);
451
}
452

453
// Version information
454
public final class Version implements Comparable<Version> {
455
    public static Version getCurrent();
456
    public static Version create(int... versions);
457
    public boolean isSnapshot();
458
    public boolean isRelease();
459
    public int compareTo(Version other);
460
}
461

462
// Options system types
463
public final class OptionDescriptors implements Iterable<OptionDescriptor> {
464
    public OptionDescriptor get(String name);
465
    public Iterator<OptionDescriptor> iterator();
466
}
467

468
public final class OptionDescriptor {
469
    public String getName();
470
    public OptionKey<?> getKey();
471
    public String getHelp();
472
    public OptionCategory getCategory();
473
}
474

475
public enum OptionCategory {
476
    USER, EXPERT, DEBUG
477
}
478

479
// Base interfaces for word types
480
public interface PointerBase extends ComparableWord {
481
    boolean isNull();
482
    boolean isNonNull();
483
}
484

485
public interface SignedWord extends ComparableWord {
486
    SignedWord add(SignedWord val);
487
    SignedWord subtract(SignedWord val);
488
    SignedWord multiply(SignedWord val);
489
}
490

491
// Supplier interface for object pools
492
public interface Supplier<T> {
493
    T get();
494
}
495

496
// File system types
497
public interface Path {
498
    String toString();
499
    Path getParent();
500
    Path getFileName();
501
}
502

503
public enum AccessMode {
504
    READ, WRITE, EXECUTE
505
}
506

507
public interface LinkOption {
508
}
509

510
public interface OpenOption {
511
}
512

513
public interface FileAttribute<T> {
514
    String name();
515
    T value();
516
}
517

518
// Standard Java types referenced in APIs
519
public interface Map<K, V> {
520
    V get(Object key);
521
    V put(K key, V value);
522
    Set<K> keySet();
523
}
524

525
public interface Set<E> {
526
    boolean add(E e);
527
    boolean contains(Object o);
528
    Iterator<E> iterator();
529
}
530

531
public interface Iterator<E> {
532
    boolean hasNext();
533
    E next();
534
}
535

536
public interface Iterable<T> {
537
    Iterator<T> iterator();
538
}
539

540
public interface Reader extends AutoCloseable {
541
    int read();
542
    void close();
543
}
544

545
public class Thread {
546
    public void start();
547
    public void join();
548
    public static Thread currentThread();
549
}
550

551
public interface ThreadLocal<T> {
552
    T get();
553
    void set(T value);
554
}
555

556
public interface Runnable {
557
    void run();
558
}
559

560
public interface AutoCloseable {
561
    void close();
562
}
563
```