Migrating JavaScript from Rhino to GraalVM
DirX Identity V8.10 supports both Rhino and GraalVM JavaScript (GraalJS). Where the script definition supports engine selection, you can migrate one script at a time and leave other scripts on Rhino. Changing the engine does not rewrite the script.
Before You Migrate
-
Use a DirX Identity build that supports the GraalVM executor and the Java runtime supported by that build. See Update Tomcat and Java Environment. Selecting the GraalVM executor is a script configuration change, not a change to the JVM that runs DirX Identity.
-
Inventory custom JavaScript and its callers. Include inline XML scripts, references to JavaScript entries, and provisioning rule actions. Record the current engine setting, the expected result type, and any changes the script makes to DirX Identity objects.
-
Back up both the script source and its configuration. In a test environment, capture the Rhino behavior with representative inputs, including empty values and error cases.
Selecting the JavaScript Executor
In an XML object description, set the language attribute on the <script> element that defines or references the script. Use exactly js-rhino to select Rhino or js-graalvm to select GraalVM. The setting is per script definition, not per JavaScript file. The scriptContext variable still provides access to the application context; do not set the language inside the script body.
For example, the following are two versions of an inline property default script. Use only one definition at a time:
<script name="defaultDescription" language="js-rhino" return="result">
<![CDATA[
var result = "New account";
]]>
</script>
<script name="defaultDescription" language="js-graalvm" return="result">
<![CDATA[
var result = "New account";
]]>
</script>
For a referenced script, add language to the same <script> element as the reference attribute. If several definitions reference the same source, check each one before editing the shared source. Use separate entries during the transition if the Rhino and GraalVM versions of the code differ.
For a provisioning rule action implemented as a JavaScript operation, set the operation object’s dxrType attribute to javascript/js-rhino or javascript/js-graalvm. The rule runner reads the script’s result from the global success variable; keep that variable when migrating the action.
In V8.10, these definitions use Rhino if no engine is specified. An unrecognized language value logs a warning and falls back to the default. Set the engine explicitly for scripts under migration so a test does not accidentally run on Rhino. Other scripting features may choose the engine differently; do not assume that they accept the XML attribute or operation type described here.
Adapting JavaScript Code
Import Java Classes Explicitly
Replace Rhino-specific imports such as importPackage() and importClass() with Java.type() and a fully qualified class name. Do not rely on implicit package globals or enable compatibility modes to avoid porting the code.
importPackage(java.util);
var names = new ArrayList();
names.add("example");
var ArrayList = Java.type("java.util.ArrayList");
var names = new ArrayList();
names.add("example");
Check Strings, Java Calls, and Result Types
-
Use
value.lengthrather thanvalue.length()for strings in GraalVM, including strings returned by Java. Check fornullorundefinedfirst if the property is optional. -
Where Java methods are overloaded, verify which overload receives your arguments. If necessary, select it explicitly, for example
names["remove(int)"](0)for index-based removal from a Java list. -
Keep the caller’s result contract. If a definition specifies
return="result", assign a top-levelvar resulton every relevant code path. Do not replace it with a function-local variable, a top-levelletorconst, or an assumption about the script’s last expression. -
Distinguish JavaScript arrays from Java arrays and collections. Verify the type required by the consumer before adding conversions. For example, V8.10.16 improves conversion to Java
Object[]for assigned-group filters inTSAccounts.xml; testGroups.Assignedwith no groups and with multiple groups. -
Review Rhino-specific exception handling and implicit type coercion. Test both successful and failing Java calls rather than assuming Rhino exception objects behave the same way in GraalVM.
Rolling Out and Troubleshooting
-
Start with a low-risk script. Port its Java interoperability code, select GraalVM in the configuration, and apply the updated configuration to the component that runs the script.
-
Exercise the script through its real caller, such as a property edit in DirX Identity Manager or Web Center, or a provisioning rule evaluation. Compare returned values and types, saved attributes, and rule outcomes with the Rhino baseline. Repeat execution with different objects to check that the script does not depend on state from a previous invocation.
-
If the script fails, check the executing component’s logs for the script name, error message, and source location when available:
-
If the engine setting appears to have no effect, check the exact selector value and confirm the component loaded the updated definition.
-
If a class or import is not found, check the
Java.type()class name and that the required library is available to the executing component. -
If the result is missing or rejected, check the configured result variable, its scope and value on each path, and the type the caller expects.
-
-
Deploy validated scripts in small batches. If a script has to be rolled back, restore both its previous source and engine setting, then reapply the configuration. Switching to Rhino alone can leave it running code written for GraalVM.
For more Java interoperability examples, see the GraalJS Migration Guide from Rhino to GraalJS and Java Interoperability guide.
Further Useful Links for GraalVM Migration
https://github.com/oracle/graaljs/blob/master/docs/user/RhinoMigrationGuide.md https://github.com/oracle/graaljs/blob/master/docs/user/NashornMigrationGuide.md https://github.com/oracle/graaljs/blob/master/docs/user/JavaScriptCompatibility.md https://github.com/oracle/graaljs/blob/master/docs/user/FAQ.md