Introduction to Nashorn

1. Introduction

This article is focused on Nashorn – the new default JavaScript engine for the JVM as of Java 8.

Many sophisticated techniques have been used to make Nashorn orders of magnitude more performant than its predecessor called Rhino, so it is a worthwhile change.

Let’s have a look at some of the ways in which it can be used.

2. Command Line

JDK 1.8 includes a command line interpreter called jjs which can be used to run JavaScript files or, if started with no arguments, as a REPL (interactive shell):

$ $JAVA_HOME/bin/jjs hello.js
Hello World

Here the file hello.js contains a single instruction: print(“Hello World”);

The same code can be run in the interactive manner:

$ $JAVA_HOME/bin/jjs
jjs> print("Hello World")
Hello World

You can also instruct the *nix runtime to use jjs for running a target script by adding a #!$JAVA_HOME/bin/jjs as the first line:

#!$JAVA_HOME/bin/jjs
var greeting = "Hello World";
print(greeting);

And then the file can be run as normal:

$ ./hello.js
Hello World

3. Embedded Script Engine

The second and probably more common way to run JavaScript from within the JVM is via the ScriptEngine. JSR-223 defines a set of scripting APIs, allowing for a pluggable script engine architecture that can be used for any dynamic language (provided it has a JVM implementation, of course).

Let’s create a JavaScript engine:

ScriptEngine engine = new ScriptEngineManager().getEngineByName("nashorn");

Object result = engine.eval(
   "var greeting='hello world';" +
   "print(greeting);" +
   "greeting");

Here we create a new ScriptEngineManager and immediately ask it to give us a ScriptEngine named nashorn. Then, we pass a couple instructions and obtain the result which predictably, turns out to be a String “hello world“.

4. Passing Data to the Script

Data can be passed into the engine by defining a Bindings object and passing it as a second parameter to the eval function:

Bindings bindings = engine.createBindings();
bindings.put("count", 3);
bindings.put("name", "baeldung");

String script = "var greeting='Hello ';" +
  "for(var i=count;i>0;i--) { " +
  "greeting+=name + ' '" +
  "}" +
  "greeting";

Object bindingsResult = engine.eval(script, bindings);

Running this snippet produces: “Hello baeldung baeldung baeldung“.

5. Invoking JavaScript Functions

It’s, of course, possible to call JavaScript functions from your Java code:

engine.eval("function composeGreeting(name) {" +
  "return 'Hello ' + name" +
  "}");
Invocable invocable = (Invocable) engine;

Object funcResult = invocable.invokeFunction("composeGreeting", "baeldung");

This will return “Hello baeldung“.

6. Using Java Objects

Since we are running in the JVM it is possible to use native Java objects from within JavaScript code.

This is accomplished by using a Java object:

Object map = engine.eval("var HashMap = Java.type('java.util.HashMap');" +
  "var map = new HashMap();" +
  "map.put('hello', 'world');" +
  "map");

7. Language Extensions

Nashorn is targeting ECMAScript 5.1 but it does provide extensions to make JavaScript usage a tad nicer.

7.1. Iterating Collections With For-Each

For-each is a convenient extension to make iteration over various collections easier:

String script = "var list = [1, 2, 3, 4, 5];" +
  "var result = '';" +
  "for each (var i in list) {" +
  "result+=i+'-';" +
  "};" +
  "print(result);";

engine.eval(script);

Here, we join elements of an array by using for-each iteration construct.

The resulting output will be 1-2-3-4-5-.

7.2. Function Literals

In simple function declarations you can omit curly braces:

function increment(in) ++in

Obviously, this can only be done for simple, one-liner functions.

7.3. Conditional Catch Clauses

It is possible to add guarded catch clauses that only execute if the specified condition is true:

try {
    throw "BOOM";
} catch(e if typeof e === 'string') {
    print("String thrown: " + e);
} catch(e) {
    print("this shouldn't happen!");
}

This will print “String thrown: BOOM“.

7.4. Typed Arrays and Type Conversions

It is possible to use Java typed arrays and to convert to and from JavaScript arrays:

function arrays(arr) {
    var javaIntArray = Java.to(arr, "int[]");
    print(javaIntArray[0]);
    print(javaIntArray[1]);
    print(javaIntArray[2]);
}

Nashorn performs some type conversions here to make sure that all the values from the dynamically typed JavaScript array can fit into the integer-only Java arrays.

The result of calling above function with argument [100, “1654”, true] results in the output of 100, 1654 and 1 (all numbers).

The String and boolean values were implicitly converted to their logical integer counterparts.

7.5. Setting Object’s Prototype With Object.setPrototypeOf

Nashorn defines an API extension that enables us to change the prototype of an object:

Object.setPrototypeOf(obj, newProto)

This function is generally considered a better alternative to Object.prototype.__proto__ so it should be the preferred way to set object’s prototype in all new code.

7.6. Magical __noSuchProperty__ and __noSuchMethod__

It is possible to define methods on an object that will be invoked whenever an undefined property is accessed or an undefined method is invoked:

var demo = {
    __noSuchProperty__: function (propName) {
        print("Accessed non-existing property: " + propName);
    },
    
    __noSuchMethod__: function (methodName) {
        print("Invoked non-existing method: " + methodName);
    }
};

demo.doesNotExist;
demo.callNonExistingMethod()

This will print:

Accessed non-existing property: doesNotExist
Invoked non-existing method: callNonExistingMethod

7.7. Bind Object Properties With Object.bindProperties

Object.bindProperties can be used to bind properties from one object into another:

var first = {
    name: "Whiskey",
    age: 5
};

var second = {
    volume: 100
};

Object.bindProperties(first, second);

print(first.volume);

second.volume = 1000;
print(first.volume);

Notice, that this creates is a “live” binding and any updates to the source object are also visible through the binding target.

7.8. Locations

Current file name, directory and a line can be obtained from global variables __FILE__, __DIR__, __LINE__:

print(__FILE__, __LINE__, __DIR__)

7.9. Extensions to String.prototype

There are two simple, but very useful extensions that Nashorn provides on the String prototype. These are trimRight and trimLeft functions which, unsurprisingly, return a copy of the String with the whitespace removed:

print("   hello world".trimLeft());
print("hello world     ".trimRight());

Will print “hello world” twice without leading or trailing spaces.

7.10. Java.asJSONCompatible Function

Using this function, we can obtain an object that is compatible with Java JSON libraries expectations.

Namely, that if it itself, or any object transitively reachable through it is a JavaScript array, then such objects will be exposed as JSObject that also implements the List interface for exposing the array elements.

Object obj = engine.eval("Java.asJSONCompatible(
  { number: 42, greet: 'hello', primes: [2,3,5,7,11,13] })");
Map<String, Object> map = (Map<String, Object>)obj;
 
System.out.println(map.get("greet"));
System.out.println(map.get("primes"));
System.out.println(List.class.isAssignableFrom(map.get("primes").getClass()));

This will print “hello” followed by [2, 3, 5, 7, 11, 13] followed by true.

8. Loading Scripts

It’s also possible to load another JavaScript file from within the ScriptEngine:

load('classpath:script.js')

A script can also be loaded from a URL:

load('/script.js')

Keep in mind that JavaScript does not have a concept of namespaces so everything gets piled on into the global scope. This makes it possible for loaded scripts to create naming conflicts with your code or each other. This can be mitigated by using the loadWithNewGlobal function:

var math = loadWithNewGlobal('classpath:math_module.js')
math.increment(5);

With the following math_module.js:

var math = {
    increment: function(num) {
        return ++num;
    }
};

math;bai

Here we are defining an object named math that has a single function called increment. Using this paradigm we can even emulate basic modularity!

8. Conclusion

This article explored some features of the Nashorn JavaScript engine. Examples showcased here used string literal scripts, but for real-life scenarios, you most likely want to keep your script in separate files and load them using a Reader class.

As always, the code in this write-up is all available over on GitHub.