GraalJS ScriptEngine

GraalJS ScriptEngine provides a JSR-223 compliant implementation for executing JavaScript code in Java applications using the high-performance GraalJS runtime. This library bridges Java and JavaScript environments through the standard javax.script.ScriptEngine API, enabling seamless integration of JavaScript scripting capabilities with full ECMAScript compliance and excellent performance.

Package Information

• Package Name: js-scriptengine
• Package Type: maven
• Language: Java
• Group ID: org.graalvm.js
• Artifact ID: js-scriptengine
• Installation: Add Maven dependency and ensure module is on module path

<dependency>
    <groupId>org.graalvm.js</groupId>
    <artifactId>js-scriptengine</artifactId>
    <version>24.2.1</version>
</dependency>
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>js</artifactId>
    <version>24.2.1</version>
    <type>pom</type>
</dependency>

Core Imports

import javax.script.*;
import com.oracle.truffle.js.scriptengine.GraalJSScriptEngine;
import com.oracle.truffle.js.scriptengine.GraalJSEngineFactory;
import org.graalvm.polyglot.Context;
import org.graalvm.polyglot.Engine;

Basic Usage

// Standard JSR-223 approach
ScriptEngineManager manager = new ScriptEngineManager();
ScriptEngine engine = manager.getEngineByName("js");

// Execute JavaScript code
Object result = engine.eval("Math.max(10, 20)");
System.out.println(result); // 20

// Set variables in JavaScript scope
engine.put("name", "World");
String greeting = (String) engine.eval("'Hello, ' + name + '!'");
System.out.println(greeting); // Hello, World!

// Direct GraalJS creation with default settings
GraalJSScriptEngine graalEngine = GraalJSScriptEngine.create();
Object value = graalEngine.eval("42 * 2");
System.out.println(value); // 84

Architecture

GraalJS ScriptEngine is built around several key components:

• GraalJSScriptEngine: The main JSR-223 compliant ScriptEngine implementation providing JavaScript execution
• GraalJSEngineFactory: Factory for creating ScriptEngine instances with proper service registration
• GraalJSBindings: Specialized bindings that bridge ScriptEngine and GraalJS polyglot contexts
• Polyglot Integration: Deep integration with GraalVM's polyglot capabilities for performance and interoperability
• Configuration System: Flexible configuration through bindings, system properties, or direct context builders

Capabilities

Script Engine Core

Main JavaScript execution functionality through the JSR-223 compliant ScriptEngine interface. Provides script evaluation, compilation, and variable binding capabilities.

// Main execution methods
Object eval(String script) throws ScriptException;
Object eval(Reader reader) throws ScriptException;
Object eval(String script, ScriptContext context) throws ScriptException;
Object eval(Reader reader, ScriptContext context) throws ScriptException;

// Variable management
Object get(String key);
void put(String key, Object value);
Bindings getBindings(int scope);
void setBindings(Bindings bindings, int scope);
Bindings createBindings();

Script Engine Core

Engine Factory

ScriptEngineFactory implementation for service discovery and engine creation with metadata about supported languages, MIME types, and file extensions.

ScriptEngine getScriptEngine();
String getEngineName(); // Returns "Graal.js"
String getEngineVersion();
List<String> getNames(); // JavaScript engine aliases
List<String> getMimeTypes(); // Supported MIME types
List<String> getExtensions(); // ["js", "mjs"]
String getLanguageName(); // "ECMAScript"
String getLanguageVersion(); // "ECMAScript 262 Edition 11"

Engine Factory

Configuration & Context Management

Advanced configuration capabilities through magic bindings, system properties, and direct polyglot context builders for fine-grained control over security and performance settings.

// Direct creation with custom configuration
static GraalJSScriptEngine create();
static GraalJSScriptEngine create(Engine engine, Context.Builder contextConfig);

// Polyglot context access
Context getPolyglotContext();
Context getPolyglotContext(ScriptContext scriptContext);
Engine getPolyglotEngine();

// Resource management
void close(); // AutoCloseable implementation

Configuration & Context Management

Security Considerations

By default, GraalJS ScriptEngine runs in a sandboxed environment with limited access to host resources. Access can be granted through configuration:

• Host Access: Access to Java objects and classes
• I/O Access: File system and network operations
• Native Access: Access to native libraries
• Thread Creation: Ability to create new threads
• Class Loading: Dynamic class loading capabilities

Always configure security settings appropriately for your use case to maintain application security.

Performance Tips

• Use CompiledScript: For repeated execution, compile scripts once and reuse
• Reuse Engines: Create engine instances once and reuse across evaluations
• Thread Safety: Each thread should have its own ScriptEngine instance
• Context Management: Close engines and contexts when no longer needed to free resources

Common Use Cases

• Configuration Scripts: Dynamic configuration using JavaScript expressions
• Rule Engines: Business rule evaluation with JavaScript logic
• Template Processing: Dynamic content generation with JavaScript templating
• Plugin Systems: Extensible applications with JavaScript-based plugins
• Data Processing: Transform and manipulate data using JavaScript functions
• Legacy Migration: Migration path from Nashorn to modern JavaScript runtime