tessl/maven-org-graalvm-polyglot--polyglot

GraalVM Polyglot API for embedding multiple programming languages in Java applications with secure language interoperability

—

Pending

Overview

Eval results

Files

Engine Management

Name: tessl/maven-org-graalvm-polyglot--polyglot
Author: tessl

Engine management provides the central execution infrastructure for polyglot programming. Engines coordinate multiple contexts, manage compilation caches, provide access to installed languages and instruments, and enable resource sharing across contexts.

Capabilities

Engine Creation

Create polyglot engines for shared execution infrastructure.

public final class Engine implements AutoCloseable {
    public static Engine create();
}

Usage:

// Create default engine
Engine engine = Engine.create();

// Use engine with multiple contexts
try (Context ctx1 = Context.newBuilder("js").engine(engine).build();
     Context ctx2 = Context.newBuilder("python").engine(engine).build()) {
    // Both contexts share the same engine
}

engine.close();

Engine Builder

Configure engines with advanced options before creation.

public static final class Engine.Builder {
    public Engine.Builder allowExperimentalOptions(boolean enabled);
    public Engine.Builder option(String key, String value);
    public Engine.Builder options(Map<String, String> options);
    public Engine.Builder out(OutputStream out);
    public Engine.Builder err(OutputStream err);
    public Engine.Builder in(InputStream in);
    public Engine.Builder sandbox(SandboxPolicy policy);
    public Engine.Builder useSystemProperties(boolean enabled);
    public Engine build();
}

Usage:

Engine engine = Engine.newBuilder()
    .allowExperimentalOptions(true)
    .option("js.ecmascript-version", "2022")
    .option("python.ForceImportSite", "false")
    .sandbox(SandboxPolicy.CONSTRAINED)
    .build();

Language Discovery

Access information about installed language implementations.

public Map<String, Language> getLanguages();

Usage:

Engine engine = Engine.create();
Map<String, Language> languages = engine.getLanguages();

for (Map.Entry<String, Language> entry : languages.entrySet()) {
    String id = entry.getKey();
    Language lang = entry.getValue();
    
    System.out.println("Language: " + id);
    System.out.println("  Name: " + lang.getName());
    System.out.println("  Version: " + lang.getVersion());
    System.out.println("  Implementation: " + lang.getImplementationName());
    System.out.println("  MIME types: " + lang.getMimeTypes());
}

// Check if specific language is available
if (languages.containsKey("js")) {
    System.out.println("JavaScript is available");
}

Instrument Discovery

Access information about installed instrumentation tools.

public Map<String, Instrument> getInstruments();

Usage:

Engine engine = Engine.create();
Map<String, Instrument> instruments = engine.getInstruments();

for (Map.Entry<String, Instrument> entry : instruments.entrySet()) {
    String id = entry.getKey();
    Instrument instrument = entry.getValue();
    
    System.out.println("Instrument: " + id);
    System.out.println("  Name: " + instrument.getName());
    System.out.println("  Version: " + instrument.getVersion());
    
    // Lookup instrument services
    if (id.equals("profiler")) {
        CPUSampler sampler = instrument.lookup(CPUSampler.class);
        if (sampler != null) {
            sampler.setCollecting(true);
        }
    }
}

Engine Options

Access engine-wide configuration options.

public OptionValues getOptions();

Usage:

Engine engine = Engine.create();
OptionValues options = engine.getOptions();

// Access option values
for (OptionDescriptor desc : options.getDescriptors()) {
    System.out.println("Option: " + desc.getName());
    System.out.println("  Value: " + options.get(desc.getKey()));
    System.out.println("  Help: " + desc.getHelp());
}

Compilation Cache

Manage compilation caches for performance optimization.

public void storeCache(Cache cache);
public Collection<Source> getCachedSources();

Usage:

Engine engine = Engine.create();

// Create and store cache
Cache cache = Cache.newBuilder()
    .maximumSize(100)
    .expireAfterAccess(Duration.ofMinutes(30))
    .build();
engine.storeCache(cache);

// Check cached sources
Collection<Source> cachedSources = engine.getCachedSources();
System.out.println("Cached sources: " + cachedSources.size());

Resource Management

Manage engine lifecycle and resource cleanup.

public void close();
public void close(boolean cancelIfExecuting);

Usage:

Engine engine = Engine.create();

// Normal close (waits for executing contexts)
engine.close();

// Force close (cancels executing contexts)
engine.close(true);

// Using try-with-resources (recommended)
try (Engine engine = Engine.create()) {
    // Use engine
} // Automatically closed

GraalVM Home Discovery

Locate GraalVM installation directory.

public static Path findHome();
public static void copyResources(Path targetFolder, String... resources);

Usage:

// Find GraalVM home directory
Path graalHome = Engine.findHome();
System.out.println("GraalVM home: " + graalHome);

// Copy GraalVM resources
Engine.copyResources(Paths.get("/tmp/graal-resources"), 
    "languages/js", "tools/profiler");

Advanced Usage

Shared Engine Pattern

Share engines across multiple contexts for better resource utilization:

Engine sharedEngine = Engine.create();

// Multiple contexts sharing the same engine
List<Context> contexts = new ArrayList<>();
for (int i = 0; i < 10; i++) {
    Context ctx = Context.newBuilder("js")
        .engine(sharedEngine)
        .build();
    contexts.add(ctx);
}

// Use contexts...

// Clean up
contexts.forEach(Context::close);
sharedEngine.close();

Engine Configuration

Configure engines for specific use cases:

// High-performance engine
Engine performanceEngine = Engine.newBuilder()
    .option("js.v8-compat", "true")
    .option("js.ecmascript-version", "2022")
    .option("python.EmulateJython", "true")
    .build();

// Sandboxed engine
Engine sandboxEngine = Engine.newBuilder()
    .sandbox(SandboxPolicy.ISOLATED)
    .option("js.allow-eval", "false")
    .build();

// Development engine with debugging
ByteArrayOutputStream debugOut = new ByteArrayOutputStream();
Engine debugEngine = Engine.newBuilder()
    .allowExperimentalOptions(true)
    .option("inspect", "9229")
    .out(debugOut)
    .err(debugOut)
    .build();

Thread Safety

Engines are thread-safe and can be shared across multiple threads and contexts. Multiple contexts can safely use the same engine concurrently.

Performance Considerations

Engine Reuse: Reusing engines across contexts improves performance by sharing compilation caches and language implementations
Warm-up: Engines and languages have warm-up phases; reusing engines amortizes this cost
Memory: Engines maintain compilation caches which consume memory; configure cache limits appropriately
Resource Sharing: Shared engines enable better resource utilization in multi-context applications

Install with Tessl CLI

npx tessl i tessl/maven-org-graalvm-polyglot--polyglot

docs

context-management.md

engine-management.md

execution-monitoring.md

index.md

io-abstractions.md

proxy-system.md

security-configuration.md

source-management.md

value-operations.md

tile.json

tessl/maven-org-graalvm-polyglot--polyglot