or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

c-interop.mdcollections.mdconfig.mdindex.mdjni-utils.mdnative-bridge.mdnative-image.mdpolyglot.mdsubstitutions.mdword.md
tile.json

tessl/maven-org-graalvm-sdk--graal-sdk

GraalVM Standard Development Kit providing APIs for polyglot language embedding, native AOT compilation, memory-efficient collections, low-level memory access, JNI utilities, and native bridge communication.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.graalvm.sdk/graal-sdk@26.0.x

To install, run

npx @tessl/cli install tessl/maven-org-graalvm-sdk--graal-sdk@26.0.0

index.mddocs/

GraalVM SDK

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.

Package Information

  • Package Name: graal-sdk
  • Group ID: org.graalvm.sdk
  • Artifact ID: graal-sdk
  • Package Type: maven
  • Language: Java
  • Installation: Add to Maven dependencies with <groupId>org.graalvm.sdk</groupId> and <artifactId>graal-sdk</artifactId>

Core Imports

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

// Polyglot language embedding
import org.graalvm.polyglot.*;
import org.graalvm.polyglot.proxy.*;
import org.graalvm.polyglot.io.*;

// Native Image AOT compilation
import org.graalvm.nativeimage.*;
import org.graalvm.nativeimage.hosted.*;
import org.graalvm.nativeimage.c.function.*;
import org.graalvm.nativeimage.c.type.*;

// Memory-efficient collections
import org.graalvm.collections.*;

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

// Installation and configuration
import org.graalvm.home.*;
import org.graalvm.options.*;

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

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

// Native Image substitutions (compatibility only)
import com.oracle.svm.core.annotate.*;

Basic Usage

import org.graalvm.polyglot.*;
import org.graalvm.collections.*;
import org.graalvm.word.*;

public class GraalVMExample {
    public static void main(String[] args) {
        // Polyglot language embedding
        try (Context context = Context.create()) {
            // Execute JavaScript code
            Value result = context.eval("js", "Math.max(42, 100)");
            System.out.println("JavaScript result: " + result.asInt());
            
            // Execute Python code (if available)
            Value pyResult = context.eval("python", "len([1, 2, 3])");
            System.out.println("Python result: " + pyResult.asInt());
        }
        
        // Use memory-efficient collections
        EconomicMap<String, Integer> map = EconomicMap.create();
        map.put("count", 42);
        System.out.println("Map value: " + map.get("count"));
        
        // Low-level word operations (in native image context)
        UnsignedWord size = WordFactory.unsigned(1024);
        UnsignedWord doubled = size.multiply(2);
        System.out.println("Doubled size: " + doubled.rawValue());
    }
}

Architecture

The GraalVM SDK is built around several key architectural components:

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

Capabilities

Polyglot Language Embedding

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

// Core polyglot context management
public final class Context implements AutoCloseable {
    public static Context create(String... permittedLanguages);
    public static Context.Builder newBuilder(String... permittedLanguages);
    public Value eval(String languageId, CharSequence source);
    public Value getBindings(String languageId);
    public void close();
}

public final class Value {
    public <T> T as(Class<T> targetType);
    public boolean asBoolean();
    public int asInt();
    public long asLong();
    public double asDouble();
    public String asString();
    public Value execute(Object... arguments);
    public Value getMember(String key);
    public boolean canExecute();
    public boolean hasMembers();
}

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

public interface ProcessHandler {
    Process start(ProcessBuilder processBuilder);
    ProcessBuilder.Redirect redirect(ProcessBuilder.Redirect redirect);
}

Polyglot Language Embedding

Native Image Compilation

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

// Core native image runtime information
public final class ImageInfo {
    public static boolean inImageCode();
    public static boolean inImageBuildtimeCode(); 
    public static boolean inImageRuntimeCode();
    public static boolean isExecutable();
    public static boolean isSharedLibrary();
}

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

// Build-time customization
public interface Feature {
    void afterRegistration(AfterRegistrationAccess access);
    void beforeAnalysis(BeforeAnalysisAccess access);
    void duringAnalysis(DuringAnalysisAccess access);
    void afterAnalysis(AfterAnalysisAccess access);
}

Native Image Compilation

Memory-Efficient Collections

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.

// Memory-efficient map with dynamic representation
public interface EconomicMap<K, V> extends UnmodifiableEconomicMap<K, V> {
    static <K, V> EconomicMap<K, V> create();
    static <K, V> EconomicMap<K, V> create(Equivalence strategy);
    V put(K key, V value);
    V removeKey(K key);
    void clear();
    void putAll(EconomicMap<K, V> other);
}

// Memory-efficient set implementation  
public interface EconomicSet<E> extends UnmodifiableEconomicSet<E> {
    static <E> EconomicSet<E> create();
    static <E> EconomicSet<E> create(Equivalence strategy);
    boolean add(E element);
    boolean remove(E element);
    void clear();
}

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

// Lock-free radix tree for fast string lookups
public final class LockFreePrefixTree {
    static LockFreePrefixTree create();
    void put(String key, Object value);
    Object get(String key);
    Set<String> getKeysWithPrefix(String prefix);
}

Memory-Efficient Collections

Low-Level Memory Access

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

// Machine word-sized unsigned arithmetic
public interface UnsignedWord extends ComparableWord {
    UnsignedWord add(UnsignedWord val);
    UnsignedWord subtract(UnsignedWord val);
    UnsignedWord multiply(UnsignedWord val);
    UnsignedWord unsignedDivide(UnsignedWord val);
    UnsignedWord and(UnsignedWord val);
    UnsignedWord or(UnsignedWord val);
}

// Direct memory pointer access
public interface Pointer extends UnsignedWord, PointerBase {
    byte readByte(UnsignedWord offset);
    void writeByte(UnsignedWord offset, byte val);
    int readInt(UnsignedWord offset);
    void writeInt(UnsignedWord offset, int val);
}

Low-Level Memory Access

Installation and Configuration

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

// GraalVM installation discovery
public abstract class HomeFinder {
    public static HomeFinder getInstance();
    public abstract String getHomeFolder();
    public abstract Version getVersion();
    public abstract Map<String, String> getLanguageHomes();
    public abstract Map<String, String> getToolHomes();
}

// Type-safe option management
public final class OptionKey<T> {
    public T getValue(OptionValues values);
    public boolean hasBeenSet(OptionValues values);
}

public final class OptionDescriptor {
    public String getName();
    public OptionKey<?> getKey();
    public String getHelp();
    public OptionCategory getCategory();
}

Installation and Configuration

C Interoperability

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

// C function pointer types
public interface CFunctionPointer extends CodePointer, RelocatedPointer {
}

// Typed C primitive pointers
public interface CIntPointer extends PointerBase {
    int read();
    int read(int index);
    void write(int value);
    void write(int index, int value);
}

// Generic C pointer operations
public interface CCharPointer extends PointerBase {
    byte read();
    void write(byte value);
    CCharPointer addressOf(int index);
}

C Interoperability

JNI Utils

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

// Core JNI utility functions
public final class JNI {
    public static <T> T NewLocalRef(T obj);
    public static void DeleteLocalRef(Object obj);
    public static <T> T NewGlobalRef(T obj);
    public static void DeleteGlobalRef(Object obj);
    public static Class<?> GetObjectClass(Object obj);
    public static boolean ExceptionCheck();
    public static void ExceptionClear();
}

// Scoped JNI method execution
public final class JNIMethodScope implements AutoCloseable {
    public static JNIMethodScope scope();
    public <T> T scope(Supplier<T> operation);
    public void scope(Runnable operation);
    public void close();
}

// Entry point generation annotation
@Target(ElementType.METHOD)
public @interface JNIEntryPoint {
    String name() default "";
    String signature() default "";
    boolean exceptionHandling() default true;
}

JNI Utils

Native Bridge

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

// Bridge generation annotations
@Target(ElementType.TYPE)
public @interface GenerateHotSpotToNativeBridge {
    Class<?> value();
    String name() default "";
    Class<? extends MarshallerConfig> marshallerConfig() default DefaultMarshallerConfig.class;
}

// Object marshalling interfaces
public interface BinaryMarshaller<T> {
    byte[] marshal(T object);
    T unmarshal(byte[] data);
    int estimateSize(T object);
    boolean canMarshal(T object);
}

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

// Isolate management
public static class NativeIsolateConfig {
    public final long maxHeapSize;
    public final long initialHeapSize;
    public final int stackSize;
    public final boolean debugMode;
    
    public static NativeIsolateConfig createDefault();
}

Native Bridge

Native Image Substitutions

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

// Target class identification
@Target(ElementType.TYPE)
public @interface TargetClass {
    Class<?> value() default void.class;
    String className() default "";
}

// Method replacement
@Target(ElementType.METHOD)
public @interface Substitute {
    boolean polymorphicSignature() default false;
    boolean isStatic() default false;
}

// Field value recomputation
@Target(ElementType.FIELD)
public @interface RecomputeFieldValue {
    Kind kind();
    Class<?> declClass() default void.class;
    String name() default "";
    boolean isFinal() default true;
}

Native Image Substitutions

Types

// Polyglot types
public final class Engine implements AutoCloseable {
    public static Engine create();
    public Map<String, Language> getLanguages();
    public Map<String, Instrument> getInstruments();
    public OptionDescriptors getOptions();
}

public final class Source {
    public static Source create(String language, CharSequence characters);
    public static Source.Builder newBuilder(String language, Reader source, String name);
    public String getLanguage();
    public String getName();
    public CharSequence getCharacters();
}

public final class Language {
    public String getId();
    public String getName();
    public String getVersion();
    public Set<String> getMimeTypes();
    public OptionDescriptors getOptions();
}

public final class Instrument {
    public String getId();
    public String getName();
    public String getVersion();
    public OptionDescriptors getOptions();
}

// Collection comparison strategies
public abstract class Equivalence {
    public static final Equivalence DEFAULT;
    public static final Equivalence IDENTITY;
    public abstract boolean equals(Object a, Object b);
    public abstract int hashCode(Object o);
}

// Word factory for creating values
public final class WordFactory {
    public static UnsignedWord zero();
    public static <T extends PointerBase> T nullPointer();
    public static UnsignedWord unsigned(long val);
    public static SignedWord signed(long val);
    public static <T extends PointerBase> T pointer(long val);
}

// Version information
public final class Version implements Comparable<Version> {
    public static Version getCurrent();
    public static Version create(int... versions);
    public boolean isSnapshot();
    public boolean isRelease();
    public int compareTo(Version other);
}

// Options system types
public final class OptionDescriptors implements Iterable<OptionDescriptor> {
    public OptionDescriptor get(String name);
    public Iterator<OptionDescriptor> iterator();
}

public final class OptionDescriptor {
    public String getName();
    public OptionKey<?> getKey();
    public String getHelp();
    public OptionCategory getCategory();
}

public enum OptionCategory {
    USER, EXPERT, DEBUG
}

// Base interfaces for word types
public interface PointerBase extends ComparableWord {
    boolean isNull();
    boolean isNonNull();
}

public interface SignedWord extends ComparableWord {
    SignedWord add(SignedWord val);
    SignedWord subtract(SignedWord val);
    SignedWord multiply(SignedWord val);
}

// Supplier interface for object pools
public interface Supplier<T> {
    T get();
}

// File system types
public interface Path {
    String toString();
    Path getParent();
    Path getFileName();
}

public enum AccessMode {
    READ, WRITE, EXECUTE
}

public interface LinkOption {
}

public interface OpenOption {
}

public interface FileAttribute<T> {
    String name();
    T value();
}

// Standard Java types referenced in APIs
public interface Map<K, V> {
    V get(Object key);
    V put(K key, V value);
    Set<K> keySet();
}

public interface Set<E> {
    boolean add(E e);
    boolean contains(Object o);
    Iterator<E> iterator();
}

public interface Iterator<E> {
    boolean hasNext();
    E next();
}

public interface Iterable<T> {
    Iterator<T> iterator();
}

public interface Reader extends AutoCloseable {
    int read();
    void close();
}

public class Thread {
    public void start();
    public void join();
    public static Thread currentThread();
}

public interface ThreadLocal<T> {
    T get();
    void set(T value);
}

public interface Runnable {
    void run();
}

public interface AutoCloseable {
    void close();
}