0
# Engine Factory
1

2
ScriptEngineFactory implementation for service discovery and engine creation, providing metadata about the GraalJS ScriptEngine including supported languages, MIME types, file extensions, and utility methods for JavaScript code generation.
3

4
## Capabilities
5

6
### Engine Creation
7

8
Factory methods for creating GraalJSScriptEngine instances with proper initialization and configuration.
9

10
```java { .api }
11
/**
12
 * Creates a new GraalJSScriptEngine instance with default configuration
13
 * @return New ScriptEngine instance
14
 */
15
ScriptEngine getScriptEngine();
16

17
/**
18
 * Returns the underlying polyglot engine used by created ScriptEngines
19
 * This engine is shared across multiple ScriptEngine instances for efficiency
20
 * @return GraalVM polyglot Engine instance
21
 */
22
Engine getPolyglotEngine();
23
```
24

25
**Usage Examples:**
26

27
```java
28
// Service discovery approach
29
ScriptEngineManager manager = new ScriptEngineManager();
30
ScriptEngineFactory factory = manager.getEngineByName("js").getFactory();
31
ScriptEngine engine1 = factory.getScriptEngine();
32
ScriptEngine engine2 = factory.getScriptEngine();
33

34
// Direct factory usage
35
GraalJSEngineFactory factory = new GraalJSEngineFactory();
36
ScriptEngine engine = factory.getScriptEngine();
37

38
// Access underlying polyglot engine
39
Engine polyglotEngine = ((GraalJSEngineFactory) factory).getPolyglotEngine();
40
```
41

42
### Engine Metadata
43

44
Comprehensive metadata about the JavaScript engine including names, versions, and supported formats.
45

46
```java { .api }
47
/**
48
 * Returns the display name of the script engine
49
 * @return "Graal.js"
50
 */
51
String getEngineName();
52

53
/**
54
 * Returns the version of the script engine
55
 * @return GraalVM version string
56
 */
57
String getEngineVersion();
58

59
/**
60
 * Returns the name of the scripting language
61
 * @return "ECMAScript"
62
 */
63
String getLanguageName();
64

65
/**
66
 * Returns the version of the scripting language
67
 * @return "ECMAScript 262 Edition 11"
68
 */
69
String getLanguageVersion();
70

71
/**
72
 * Returns list of supported engine names/aliases for service discovery
73
 * @return List of engine name strings
74
 */
75
List<String> getNames();
76

77
/**
78
 * Returns list of supported MIME types
79
 * @return List of MIME type strings
80
 */
81
List<String> getMimeTypes();
82

83
/**
84
 * Returns list of supported file extensions
85
 * @return List of file extension strings
86
 */
87
List<String> getExtensions();
88
```
89

90
**Engine Names/Aliases:**
91
- "js", "JS"
92
- "JavaScript", "javascript"  
93
- "ECMAScript", "ecmascript"
94
- "Graal.js", "graal.js"
95
- "Graal-js", "graal-js"
96
- "Graal.JS", "Graal-JS"
97
- "GraalJS", "GraalJSPolyglot"
98

99
**Supported MIME Types:**
100
- "application/javascript"
101
- "application/ecmascript"
102
- "text/javascript"
103
- "text/ecmascript"
104

105
**Supported File Extensions:**
106
- "js" (JavaScript files)
107
- "mjs" (ES module files)
108

109
**Usage Examples:**
110

111
```java
112
GraalJSEngineFactory factory = new GraalJSEngineFactory();
113

114
// Get engine information
115
System.out.println("Engine: " + factory.getEngineName()); // "Graal.js"
116
System.out.println("Version: " + factory.getEngineVersion()); // "24.2.1"
117
System.out.println("Language: " + factory.getLanguageName()); // "ECMAScript"
118

119
// Check supported formats
120
List<String> names = factory.getNames();
121
System.out.println("Supported names: " + names);
122
// [js, JS, JavaScript, javascript, ECMAScript, ecmascript, ...]
123

124
List<String> mimeTypes = factory.getMimeTypes();
125
System.out.println("MIME types: " + mimeTypes);
126
// [application/javascript, application/ecmascript, ...]
127

128
List<String> extensions = factory.getExtensions();
129
System.out.println("File extensions: " + extensions); // [js, mjs]
130

131
// Service discovery by different names
132
ScriptEngineManager manager = new ScriptEngineManager();
133
ScriptEngine jsEngine = manager.getEngineByName("JavaScript");
134
ScriptEngine graalEngine = manager.getEngineByName("Graal.js");
135
ScriptEngine ecmaEngine = manager.getEngineByName("ECMAScript");
136
// All return GraalJSScriptEngine instances
137

138
// Service discovery by MIME type
139
ScriptEngine mimeEngine = manager.getEngineByMimeType("application/javascript");
140

141
// Service discovery by file extension
142
ScriptEngine extEngine = manager.getEngineByExtension("js");
143
```
144

145
### Parameter Access
146

147
Access engine-specific parameters and metadata through the standard JSR-223 parameter interface.
148

149
```java { .api }
150
/**
151
 * Returns the value of engine-specific parameters
152
 * @param key Parameter key (ScriptEngine constants)
153
 * @return Parameter value or null if not supported
154
 */
155
Object getParameter(String key);
156
```
157

158
**Supported Parameters:**
159
- `ScriptEngine.NAME` → "javascript"
160
- `ScriptEngine.ENGINE` → "Graal.js"
161
- `ScriptEngine.ENGINE_VERSION` → Engine version
162
- `ScriptEngine.LANGUAGE` → "ECMAScript"
163
- `ScriptEngine.LANGUAGE_VERSION` → "ECMAScript 262 Edition 11"
164

165
**Usage Examples:**
166

167
```java
168
GraalJSEngineFactory factory = new GraalJSEngineFactory();
169

170
// Access standard parameters
171
String name = (String) factory.getParameter(ScriptEngine.NAME);
172
System.out.println("Name: " + name); // "javascript"
173

174
String engine = (String) factory.getParameter(ScriptEngine.ENGINE);
175
System.out.println("Engine: " + engine); // "Graal.js"
176

177
String version = (String) factory.getParameter(ScriptEngine.ENGINE_VERSION);
178
System.out.println("Version: " + version); // "24.2.1"
179

180
String language = (String) factory.getParameter(ScriptEngine.LANGUAGE);
181
System.out.println("Language: " + language); // "ECMAScript"
182

183
String langVersion = (String) factory.getParameter(ScriptEngine.LANGUAGE_VERSION);
184
System.out.println("Language Version: " + langVersion); // "ECMAScript 262 Edition 11"
185

186
// Unsupported parameters return null
187
Object unknown = factory.getParameter("unknown.parameter");
188
System.out.println("Unknown: " + unknown); // null
189
```
190

191
### Code Generation Utilities
192

193
Utility methods for generating JavaScript code snippets with proper syntax.
194

195
```java { .api }
196
/**
197
 * Generates JavaScript method call syntax
198
 * @param obj Object name
199
 * @param method Method name
200
 * @param args Method arguments
201
 * @return JavaScript method call string
202
 */
203
String getMethodCallSyntax(String obj, String method, String... args);
204

205
/**
206
 * Generates JavaScript output statement
207
 * @param toDisplay Expression to display
208
 * @return JavaScript print statement
209
 */
210
String getOutputStatement(String toDisplay);
211

212
/**
213
 * Combines multiple statements into a JavaScript program
214
 * @param statements JavaScript statements
215
 * @return Complete JavaScript program
216
 */
217
String getProgram(String... statements);
218
```
219

220
**Usage Examples:**
221

222
```java
223
GraalJSEngineFactory factory = new GraalJSEngineFactory();
224

225
// Generate method call syntax
226
String methodCall = factory.getMethodCallSyntax("obj", "method", "arg1", "arg2");
227
System.out.println(methodCall); // "obj.method(arg1,arg2)"
228

229
String calculatorCall = factory.getMethodCallSyntax("calc", "add", "10", "20");
230
System.out.println(calculatorCall); // "calc.add(10,20)"
231

232
// Generate output statement
233
String printStatement = factory.getOutputStatement("result");
234
System.out.println(printStatement); // "print(result)"
235

236
String printExpression = factory.getOutputStatement("2 + 3");
237
System.out.println(printExpression); // "print(2 + 3)"
238

239
// Combine statements into program
240
String program = factory.getProgram(
241
    "var x = 10",
242
    "var y = 20", 
243
    "var sum = x + y",
244
    "print(sum)"
245
);
246
System.out.println(program); // "var x = 10;var y = 20;var sum = x + y;print(sum);"
247

248
// Use generated code in scripts
249
ScriptEngine engine = factory.getScriptEngine();
250
engine.eval(program); // Prints: 30
251
```
252

253
### Service Registration
254

255
The factory is automatically registered for JSR-223 service discovery through the Java ServiceLoader mechanism.
256

257
**Service Registration File:**
258
`META-INF/services/javax.script.ScriptEngineFactory`
259
```
260
com.oracle.truffle.js.scriptengine.GraalJSEngineFactory
261
```
262

263
**Usage Examples:**
264

265
```java
266
// Automatic service discovery
267
ScriptEngineManager manager = new ScriptEngineManager();
268

269
// Discovery by engine name
270
ScriptEngine engine1 = manager.getEngineByName("js");
271
ScriptEngine engine2 = manager.getEngineByName("JavaScript");
272
ScriptEngine engine3 = manager.getEngineByName("Graal.js");
273

274
// Discovery by MIME type
275
ScriptEngine engine4 = manager.getEngineByMimeType("application/javascript");
276
ScriptEngine engine5 = manager.getEngineByMimeType("text/javascript");
277

278
// Discovery by file extension
279
ScriptEngine engine6 = manager.getEngineByExtension("js");
280
ScriptEngine engine7 = manager.getEngineByExtension("mjs");
281

282
// List all available engines
283
for (ScriptEngineFactory factory : manager.getEngineFactories()) {
284
    if (factory instanceof GraalJSEngineFactory) {
285
        System.out.println("Found GraalJS factory: " + factory.getEngineName());
286
    }
287
}
288
```
289

290
### Factory Construction
291

292
Control over polyglot engine lifecycle through factory construction options.
293

294
```java { .api }
295
/**
296
 * Default constructor - creates factory with lazy engine initialization
297
 */
298
GraalJSEngineFactory();
299

300
/**
301
 * Constructor with custom polyglot engine
302
 * @param engine Pre-configured polyglot engine to use
303
 */
304
GraalJSEngineFactory(Engine engine);
305
```
306

307
**Usage Examples:**
308

309
```java
310
// Default factory with lazy engine creation
311
GraalJSEngineFactory defaultFactory = new GraalJSEngineFactory();
312
ScriptEngine engine1 = defaultFactory.getScriptEngine();
313

314
// Factory with custom polyglot engine
315
Engine customEngine = Engine.newBuilder()
316
    .allowExperimentalOptions(true)
317
    .option("engine.MaxCompilationDelay", "10000")
318
    .build();
319

320
GraalJSEngineFactory customFactory = new GraalJSEngineFactory(customEngine);
321
ScriptEngine engine2 = customFactory.getScriptEngine();
322

323
// Multiple engines sharing the same polyglot engine
324
ScriptEngine engine3 = customFactory.getScriptEngine();
325
ScriptEngine engine4 = customFactory.getScriptEngine();
326

327
// All engines from the same factory share the polyglot engine
328
assert customFactory.getPolyglotEngine() == customEngine;
329
```