Nashorn jsr223 engine notes

Nashorn implements javax.script [http://docs.oracle.com/javase/7/docs/api/javax/script/package-frame.html] API. This page has specific info regarding nashorn script engine as well as nashorn specific scripting extensions under jdk.nashorn.api.scripting package.

Basic script engine usage document is [http://download.java.net/jdk8/docs/technotes/guides/scripting/nashorn/]

In this page, whereever "context" is mentioned it denotes javax.script.ScriptContext instance being used by script engine to evaluate scripts. "engine" represents a javax.script.ScriptEngine (a nashorn engine instance).

Setting options for Nashorn script engine

Nashorn script engine allows customization options via a System property called "nashorn.args". By default, nashorn script engine sets -scripting and -doe options. If you want to override, you can specify -Dnashorn.args=<nashorn options> in your Java command line. You can check out the list of options available by using the nashorn command line shell tool "jjs" which is available under $JDK_HOME/bin directory.

ScriptContext and Bindings

A ScriptContext contains one or more Bindings each associated each jsr223 "scope". By default there are two scopes, namely ENGINE_SCOPE and GLOBAL_SCOPE. When nashorn engine is created it creates a default context.

    ScriptContext defaultContext = engine.getContext();

The engine's default context's ENGINE_SCOPE is a wrapped instance of ECMAScript "global" scope object - which is the "this" in top level script expressions. So, you can access ECMAScript top-level objects like "Object", "Math", "RegExp", "undefined" from this scope object. Nashorn Global scope object is represented by an internal implementation class called jdk.nashorn.internal.objects.Global. Instance of this class is wrapped as jdk.nashorn.api.scripting.ScriptObjectMirror instance. ScriptObjectMirror implements javax.script.Bindings interface. GLOBAL_SCOPE object of default script context is a javax.script.SimpleBindings instance.This the user can fill with name, value pairs from the java code.

    Bindings b = engine.getContext().getBindings(ScriptContext.ENGINE_SCOPE);

    System.out.println(b.get("Object")); // gets ECMAScript "Object" constructor

    System.out.println(b.get("undefined")); // ECMAScript 'undefined' value

If you create a new ScriptContext object and use it to evaluate scripts, then ENGINE_SCOPE of that context has to be associated with a nashorn Global scope object somehow - or else script execution is not possible with that context. You could copy default script context's ENGINE_SCOPE to your new context.

    ScriptContext myContext = new SimpleScriptContext();

    myContext.setBindings(defaultContext.getBindings(ScriptContext.ENGINE_SCOPE);

    engine.eval(myScript, myContext);

In that case, script references to "Object", "Function" etc. will use definitions in the default context's ENGINE_SCOPE. But if you want you can create a new Bindings backed by a nashorn Global scope.

    myContext.setBindings(engine.createBindings(), ScriptContext.ENGINE_SCOPE);

    engine.eval(myScript, myContext); // script runs with a new ECMAScript global scope

The above code associates a fresh global scope for script. But, user can supply any ScriptContext implementation containing any Bindings object as ENGINE_SCOPE, nashorn engine cannot always assume ENGINE_SCOPE Bindings to be backed by a nashorn Global instance. Nashorn engine checks if ENGINE_SCOPE of the ScriptContext is backed by a Nashorn Global scope object or not. If not, it creates a fresh Bindings backed by nashorn Global and associates the same with the ENGINE_SCOPE that the user provided.

     ScriptContext myNewContext = new SimpleScriptContext(); // ENGINE_SCOPE is a SimpleBindings instance

     engine.eval(myScript, myNewContext); // nashorn engine associates a fresh nashorn Global with the ENGINE_SCOPE

     Object obj = myNewContext.getBindings(ScriptContext.ENGINE_SCOPE);

     Object nashornGlobal = ((Bindings)obj).get("nashorn.global"); // "nashorn.global" is the key used to associate

     ScriptObjectMirror globalMirror = (ScriptObjectMirror) nashornGlobal;

     globalMirror.get("Function"); // get "Function" constructor object from nashorn global scoe.