You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Fill in maven plugin versions.
Bump GraalJS version to 24.1.0.
Allow the example to be run without arguments.
Remove trailing whitespace.
Use maven-archetype-quickstart version 1.5.
Fix maven project name.
Flip steps 3 and 4 (specify compile dependencies first).
Explain how to set graaljs.version property in pom.xml.
Move explanation of the example app up to the code snippet (step 2).
This documentation shows you how to enable interoperability with Java and possible JavaScript-to-Java embedding scenarios.
10
+
This documentation shows you how to enable interoperability with Java and possible JavaScript-to-Java embedding scenarios.
11
11
12
12
## Enabling Java Interoperability
13
13
14
-
As of GraalVM for JDK 21, all necessary artifacts can be downloaded directly from Maven Central.
14
+
As of GraalVM for JDK 21, all necessary artifacts can be downloaded directly from Maven Central.
15
15
All artifacts relevant to embedders can be found in the Maven dependency group [`org.graalvm.polyglot`](https://central.sonatype.com/namespace/org.graalvm.polyglot).
16
16
17
17
To embed JavaScript in a Java application, add the following dependencies to the Maven configuration file:
18
18
```xml
19
-
<dependency>
20
-
<groupId>org.graalvm.polyglot</groupId>
21
-
<artifactId>polyglot</artifactId>
22
-
<version>${graaljs.version}</version>
19
+
<dependency>
20
+
<groupId>org.graalvm.polyglot</groupId>
21
+
<artifactId>polyglot</artifactId>
22
+
<version>${graaljs.version}</version>
23
23
</dependency>
24
-
<dependency>
25
-
<groupId>org.graalvm.polyglot</groupId>
26
-
<artifactId>js</artifactId>
27
-
<version>${graaljs.version}</version>
24
+
<dependency>
25
+
<groupId>org.graalvm.polyglot</groupId>
26
+
<artifactId>js</artifactId>
27
+
<version>${graaljs.version}</version>
28
28
<type>pom</type>
29
29
</dependency>
30
30
```
@@ -372,7 +372,7 @@ More detailed example usages are available in the GraalJS [unit tests](https://g
372
372
373
373
## Multithreading
374
374
375
-
GraalJS supports multithreading when used in combination with Java.
375
+
GraalJS supports multithreading when used in combination with Java.
376
376
More details about the GraalJS multithreading model can be found in the [Multithreading](Multithreading.md) documentation.
GraalJS is a fast JavaScript language implementation built on top of GraalVM.
10
+
GraalJS is a fast JavaScript language implementation built on top of GraalVM.
11
11
It is ECMAScript-compliant, provides interoperability with Java and other Graal languages, common tooling, and, if run on the GraalVM JDK, provides the best performance with the Graal JIT compiler by default.
12
-
You can also use GraalJS with Oracle JDK or OpenJDK.
12
+
You can also use GraalJS with Oracle JDK or OpenJDK.
13
13
14
14
GraalJS is a suitable replacement for projects wanting to [migrate from Nashorn or Rhino](#migration-guides) to a JavaScript engine that supports new ECMAScript standards and features.
15
15
You can easily add GraalJS to your Java application as shown below.
16
16
17
17
## Getting Started with GraalJS on the JVM
18
18
19
19
To embed JavaScript in a Java host application, enable GraalJS by adding it as a project dependency.
20
-
All necessary artifacts can be downloaded directly from Maven Central.
21
-
All artifacts relevant to embedders can be found in the Maven dependency group [org.graalvm.polyglot](https://central.sonatype.com/namespace/org.graalvm.polyglot).
20
+
All necessary artifacts can be downloaded directly from Maven Central.
21
+
All artifacts relevant to embedders can be found in the Maven dependency group [org.graalvm.polyglot](https://central.sonatype.com/namespace/org.graalvm.polyglot).
22
22
23
23
Below is the Maven configuration for a JavaScript embedding:
24
24
```xml
@@ -38,10 +38,10 @@ This enables GraalJS which is built on top of Oracle GraalVM and licensed under
38
38
Use `js-community` if you want to use GraalJS built on GraalVM Community Edition.
39
39
40
40
Go step-by-step to create a Maven project, embedding JavaScript in Java, and run it.
41
-
This example application was tested with GraalVM for JDK 22 and the GraalVM Polyglot API version 24.0.2.
41
+
This example application was tested with GraalVM for JDK 23 and the GraalVM Polyglot API version 24.1.0.
42
42
See how to install GraalVM on the [Downloads page](https://www.graalvm.org/downloads/).
43
43
44
-
1. Create a new Maven Java project named "app" in your favorite IDE or from your terminal with the following structure:
44
+
1. Create a new Maven Java project named "helloworld" in your favorite IDE or from your terminal with the following structure:
45
45
```
46
46
├── pom.xml
47
47
└── src
@@ -53,7 +53,7 @@ See how to install GraalVM on the [Downloads page](https://www.graalvm.org/downl
53
53
```
54
54
For example, you can run this command to create a new Maven project using the quickstart archetype:
String who = args.length == 0 ? "World" : args[0];
72
+
System.out.println("Hello " + who + " from Java");
72
73
try (Context context = Context.create()) {
73
74
Value value = context.eval("js", JS_CODE);
74
-
value.execute(args[0]);
75
+
value.execute(who);
75
76
}
76
77
}
77
78
}
78
79
```
80
+
This example application uses the [Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) and returns a JavaScript function as a Java value.
79
81
80
-
3. Add the regular Maven plugins for compiling and assembling the project into a JAR file with all dependencies to your _pom.xml_ file:
This example application uses the [Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) and returns a JavaScript function as a Java value.
147
-
A single JAR with all dependencies was created from language libraries.
148
-
However, we recommend splitting and using Java modules on the module path, especially if you would like to compile this application ahead of time with GraalVM Native Image.
154
+
155
+
A single JAR with all dependencies was created from language libraries.
156
+
However, we recommend splitting and using Java modules on the module path, especially if you would like to compile this application ahead of time with GraalVM Native Image.
149
157
Learn more in the [Guide to Embedding Languages](https://www.graalvm.org/reference-manual/embed-languages/#dependency-setup).
150
158
151
-
The source code unit can be represented with a String, as in the example, a file, read from URL, and [other means](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Source.html).
159
+
The source code unit can be represented with a String, as shown in the example, a file, read from URL, and [other means](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Source.html).
152
160
By wrapping the function definition (`()`), you return the function immediately:
153
161
```java
154
162
Value f = context.eval("js", "(function f(x, y) { return x + y; })");
The Polyglot API offers many other ways to access a guest language code from Java, for example, by directly accessing JavaScript objects, numbers, strings, and arrays.
180
+
The Polyglot API offers many other ways to access a guest language code from Java, for example, by directly accessing JavaScript objects, numbers, strings, and arrays.
173
181
Learn more about JavaScript to Java interoperability and find more examples in the [Java Interoperability guide](JavaInteroperability.md).
174
182
175
183
### Related Documentation
176
184
177
-
GraalJS is also available as a standalone distribution that you can download from [GitHub](https://github.com/oracle/graaljs/releases).
185
+
GraalJS is also available as a standalone distribution that you can download from [GitHub](https://github.com/oracle/graaljs/releases).
178
186
Learn more [here](https://github.com/oracle/graaljs/blob/master/README.md#standalone-distributions).
179
187
180
188
We provide the following documentation for GraalJS users:
Copy file name to clipboardExpand all lines: docs/user/ScriptEngine.md
+5-5
Original file line number
Diff line number
Diff line change
@@ -37,7 +37,7 @@ An example _pom.xml_ file can be found in the [GraalJS repository on GitHub](htt
37
37
38
38
## Recommendation for Use
39
39
40
-
To avoid unnecessary recompilation of JavaScript sources, **it is recommended to use `CompiledScript.eval`** instead of `ScriptEngine.eval`.
40
+
To avoid unnecessary recompilation of JavaScript sources, **it is recommended to use `CompiledScript.eval`** instead of `ScriptEngine.eval`.
41
41
This prevents JIT-compiled code from being garbage-collected as long as the corresponding `CompiledScript` object is alive.
42
42
43
43
Single-threaded example:
@@ -70,8 +70,8 @@ script.eval();
70
70
71
71
## Setting Options via `Bindings`
72
72
73
-
The `ScriptEngine` interface does not provide a default way to set options.
74
-
As a workaround, `GraalJSScriptEngine` supports setting some `Context` options through `Bindings`.
73
+
The `ScriptEngine` interface does not provide a default way to set options.
74
+
As a workaround, `GraalJSScriptEngine` supports setting some `Context` options through `Bindings`.
75
75
These options are:
76
76
*`polyglot.js.allowHostAccess <boolean>`
77
77
*`polyglot.js.allowNativeAccess <boolean>`
@@ -88,7 +88,7 @@ These options control the sandboxing rules applied to evaluated JavaScript code
88
88
Note that using `ScriptEngine` implies allowing experimental options.
89
89
This is an exhaustive list of allowed options to be passed via `Bindings`; in case you need to pass additional options to GraalJS, you need to manually create a `Context` as shown below.
90
90
91
-
To set an option via `Bindings`, use `Bindings.put(<option name>, true)`**before** the engine's script context is initialized.
91
+
To set an option via `Bindings`, use `Bindings.put(<option name>, true)`**before** the engine's script context is initialized.
92
92
Note that even a call to `Bindings#get(String)` may lead to a context initialization.
93
93
The following code shows how to enable `polyglot.js.allowHostAccess` via `Bindings`:
94
94
```java
@@ -108,7 +108,7 @@ Options to the JavaScript engine can be set via system properties before startin
Or, options to the JavaScript engine can be set programmatically from within a Java application before creating `ScriptEngine`.
111
+
Or, options to the JavaScript engine can be set programmatically from within a Java application before creating `ScriptEngine`.
112
112
This, however, only works for the options passed to the JavaScript engine (such as `js.ecmascript-version`), and not for the options mentioned in the example that can be set via `Bindings`.
113
113
Another caveat is that those system properties are shared by all concurrently executed `ScriptEngine`s.
0 commit comments