0
# GraalJS ScriptEngine
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: js-scriptengine
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Group ID**: org.graalvm.js
10
- **Artifact ID**: js-scriptengine
11
- **Installation**: Add Maven dependency and ensure module is on module path
12

13
```xml
14
<dependency>
15
    <groupId>org.graalvm.js</groupId>
16
    <artifactId>js-scriptengine</artifactId>
17
    <version>24.2.1</version>
18
</dependency>
19
<dependency>
20
    <groupId>org.graalvm.polyglot</groupId>
21
    <artifactId>js</artifactId>
22
    <version>24.2.1</version>
23
    <type>pom</type>
24
</dependency>
25
```
26

27
## Core Imports
28

29
```java
30
import javax.script.*;
31
import com.oracle.truffle.js.scriptengine.GraalJSScriptEngine;
32
import com.oracle.truffle.js.scriptengine.GraalJSEngineFactory;
33
import org.graalvm.polyglot.Context;
34
import org.graalvm.polyglot.Engine;
35
```
36

37
## Basic Usage
38

39
```java
40
// Standard JSR-223 approach
41
ScriptEngineManager manager = new ScriptEngineManager();
42
ScriptEngine engine = manager.getEngineByName("js");
43

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

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

53
// Direct GraalJS creation with default settings
54
GraalJSScriptEngine graalEngine = GraalJSScriptEngine.create();
55
Object value = graalEngine.eval("42 * 2");
56
System.out.println(value); // 84
57
```
58

59
## Architecture
60

61
GraalJS ScriptEngine is built around several key components:
62

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

69
## Capabilities
70

71
### Script Engine Core
72

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

75
```java { .api }
76
// Main execution methods
77
Object eval(String script) throws ScriptException;
78
Object eval(Reader reader) throws ScriptException;
79
Object eval(String script, ScriptContext context) throws ScriptException;
80
Object eval(Reader reader, ScriptContext context) throws ScriptException;
81

82
// Variable management
83
Object get(String key);
84
void put(String key, Object value);
85
Bindings getBindings(int scope);
86
void setBindings(Bindings bindings, int scope);
87
Bindings createBindings();
88
```
89

90
[Script Engine Core](./script-engine.md)
91

92
### Engine Factory
93

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

96
```java { .api }
97
ScriptEngine getScriptEngine();
98
String getEngineName(); // Returns "Graal.js"
99
String getEngineVersion();
100
List<String> getNames(); // JavaScript engine aliases
101
List<String> getMimeTypes(); // Supported MIME types
102
List<String> getExtensions(); // ["js", "mjs"]
103
String getLanguageName(); // "ECMAScript"
104
String getLanguageVersion(); // "ECMAScript 262 Edition 11"
105
```
106

107
[Engine Factory](./engine-factory.md)
108

109
### Configuration & Context Management
110

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

113
```java { .api }
114
// Direct creation with custom configuration
115
static GraalJSScriptEngine create();
116
static GraalJSScriptEngine create(Engine engine, Context.Builder contextConfig);
117

118
// Polyglot context access
119
Context getPolyglotContext();
120
Context getPolyglotContext(ScriptContext scriptContext);
121
Engine getPolyglotEngine();
122

123
// Resource management
124
void close(); // AutoCloseable implementation
125
```
126

127
[Configuration & Context Management](./configuration.md)
128

129
## Security Considerations
130

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

133
- **Host Access**: Access to Java objects and classes
134
- **I/O Access**: File system and network operations  
135
- **Native Access**: Access to native libraries
136
- **Thread Creation**: Ability to create new threads
137
- **Class Loading**: Dynamic class loading capabilities
138

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

141
## Performance Tips
142

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

148
## Common Use Cases
149

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