GraalJS Script Engine

Nashorn JavaScript Engine has been removed from Oracle Java as of version 15. The recommended replacement JavaScript engine is GraalJS.

Installation

GraalJS scripting engine is distributed with Bosch IoT Edge Services SDK packed in graaljs.scriptengine.jar bundle. This bundle can be installed on Java runtimes version 15 and above to make the GraalJS Script Engine available for use.

GrallJS bundle is installed by default by the "Scripting" KitMan script on Java runtimes version 15 and above.

Nashorn Compatibility Mode

For easy migration, GraalJS comes with Nashorn Compatibility Mode. This makes available various Java interoperability features that were available in Nashorn:

• accessing Java types from JavaScript
• the load() function
• implementing interfaces
• extending abstract classes in scripts, etc.

Full guide can be found at Nashorn Migration Guide.

The Nashorn Compatibility Mode is enabled by setting the polyglot.js.nashorn-compat Java System property to true. The property is set by default in scripting.prs properties file.

Security Options

GraalJS employs Secure by Default approach, which restricts some actions from JavaScript code - like accessing Java classes or the file system - unless explicitly permitted. Overview of these permission options is available in Secure by Default.

These permission can be set on the ScriptEngine level as described in Script Engine Implementation. The Scripting module simplifies this process, by associating system property with each permission property. The property names are the name of the permission property with prefix "mbs.scripting.graal.flags." prepended. So for example mbs.scripting.graal.flags.polyglot.js.allowHostAccess system property corresponds to permission polyglot.js.allowHostAccess. System properties are interpreted as boolean and their accepted values are true or false.

The polyglot.js.allowHostAccess permission must be enabled to make access to scripting module helper objects of Core, Script Engine Access, Registry Access and FIM Access possible. This permission is enabled by default from scripting.prs – the mbs.scripting.graal.flags.polyglot.js.allowHostAccess system property is set to true.

Compatibility Issues

There are some other minor compatibility issue, that might need addressing when switching from Nashorn to GraalJS:

• Nashorn made possible accessing java.util.Map elements using the square brackets operator:

  print(map ['name'])

  map ['name'] = 'John Doe'

  alas, this is not possible in GraalJS and the get/put methods should be used instead:

  print(map.get('name'])

  map.put('name', 'John Doe')

• GraalJS does not allow passing objects from one script context to objects in another script context. In particular, this affects how Registry Access and FIM Access helper objects are used from scripts. They are put in ScriptContext.ENGINE_SCOPE so any objects passed to them should be put in ENGINE_SCOPE Bindings too.
• Exceptions thrown from Java code, called from script code, were made available in Nashorn through ScriptException.getCause(). GraalJS introduces new type of PolyglotException. The underlying Java exception is accessed through its asHostException() method.
• GraalJS allows only one thread per script engine. If multiple threads are required, multiple script engines should be used.