Access Keys:
Skip to content (Access Key - 0)
Rhino Migration Guide
Attachments: • Added by Sundararajan Athijegannathan, last edited by Hannes Wallnoefer on May 22, 2015  (view change)
  • None

Rhino Migration Guide

jdk8 replaces Rhino based jsr-223 script engine with nashorn based jsr-223 script engine. If you are using Rhino based jsr-223 script engine in jdk 6 or jdk 7, you'll have some migration work when moving to jdk 8. This document is a  migration guide towards that task.

Nashorn extensions

Nashorn implements ECMAScript 5.1 specification with a number of syntax and API extensions as documented in Nashorn extensions Few of those are Rhino specific extensions as well. You may want to go through that document to check if a Rhino specific extension is already supported by nashorn.

Accessing Java packages and classes from script

Nashorn supports top-level "Packages" object and "java", "javax" etc. as supported by Rhino. You can use Packages object to access Java packages and classes. But, Nashorn's recommended way to access Java classes is to use Java.type.

Packages vs Java.type

Java.type is recommended because

1) It avoid multiple step resolution as done by Packages method. Class resolution is done in one step - from String name to class

2) Java.type throws ClassNotFoundException rather than silently treating an unresolved name to be package name!

java.util.vector results in a package object named "java.util.vector" whereas Java.type("java.util.vector") results in ClassNotFoundException.

Creating Java arrays from script

In Rhino, you create a Java array using Java reflection from script. In Nashorn, you can resolve to a Java array class using the same Java.type API. And array creation is done using new operator

Creating Java Array

Java array elements are accessed/modified using [] operator in both rhino as well as nashorn. Also special "length" property is supported both in rhino and nashorn.

Class object and .class property

If a java API accepts a java.lang.Class object, in rhino you can pass script representation of class "as is". In Nashorn, you've to use ".class" property (similar to Java).

Class object

In the above example, better way to create Java string array from Nashorn would be to get String[] type from Nashorn using Java.type. The example is written this way only to demonstrate ".class" property.

__proto__ magic property

Rhino's magic writable property __proto__ to read/write prototype of an object is also supported by nashorn for compatibility. But nashorn recommended way to read/write is Object.getPrototypeOf ( ) and Object.setPrototypeOf ) APIs. __proto__, while supported by nashorn, is deprecated.

JavaImporter and with

Nashorn supports JavaImporter constructor of Rhino. It is possible to locally import multiple java packages and use it within a 'with' statement.

Java exceptions

Rhino wraps Java exceptions as a script object. If you want underlying Java exception, you've to use "javaException" property to access it. Nashorn does not wrap Java exceptions. Java exception objects as thrown "as is". So, in catch blocks you can access Java exceptions "as is".

Java exceptions

Also, no Java object is wrapped as "script object" in Nashorn (unlike Java).

Implementing Java interface

Both Rhino and Nashorn support java anonymous class-like syntax to implement java interfaces in script.

Java interface

The example @ works on Nashorn as well.

Extending Java class

To extend a concrete Java class or to implement multiple interfaces, you have to use Java.extend in Nashorn - unlike "JavaAdapter" in Rhino. Java.extend is explained in Nashorn extensions document.

JavaScript vs Java Strings

Nashorn does not use wrapper objects to provide JavaScript access to Java objects like Rhino did. Since Nashorn uses java.lang.String to represent JavaScript strings internally it is not able to distinguish between native JavaScript Strings and host Java String objects, and both JavaScript and Java String methods can be invoked on any String object.

There happens to be a conflict in the case of the replace method which is defined in both languages with different semantics. In this case, the JavaScript method has precedence over the Java method. One could use explicit method selection to invoke the Java method but it is usually simpler to just use the JavaScript method.

Compatibility script

There are few Rhino/Mozilla extensions that are supported only if you load the compatibility script provided by nashorn. The compatibility script is loaded using "load('nashorn:mozilla_compat.js")

Mozilla Compatibility Script

The compatibility script implements the following Rhino extensions:

  • importClass global function to import a specific Java class. Recommended alternative is to use Java.type and assign the result to global variable
  • importPackage global function to import a specific Java package. Recommended alternative is to use JavaImporter and with statement.
  • JavaAdapter global function to subclass java class or implement java interfaces (this is a wrapper over Java.extend API of nashorn). Recommended alternative is to use Java.extend API directly.
  • __defineGetter__, __defineSetter__, __lookupGetter__ Object.prototype functions explained at Note that these are deprecated by Mozilla. Recommended alternative is to use ECMAScript compliant Object.defineProperty, Object.defineProperties API
  • toSource method on number of builtins - for example, function object to get source code of the function
  • A number of HTML generation String methods like "anchor", "sup" etc.
Compatibility script examples

loading compatibility script so that script runs on rhino and nashorn