Embedding Rhino can be done simply with good results. With more effort on the part of the embedder, the objects exposed to scripts can be customized further.

This tutorial leads you through the steps from a simple embedding to more customized, complex embeddings. Fully compilable examples are provided along the way.

The examples live in the rhino/examples directory in the distribution and in mozilla/js/rhino/examples in cvs. This document will link to them using lxr.

In this document, JavaScript code will be in green, Java code will be in green, and shell logs will be in purple.

Contents

• RunScript: A simple embedding
• Entering a Context
• Initializing standard objects
• Collecting the arguments
• Evaluating a script
• Print the result
• Exit the Context
• Expose Java APIs
• Use Java APIs
• Implementing interfaces
• Add Java objects
• JavaScript host objects
• Defining Host Objects
• Counter example
• Counter's constructors
• Class name
• Dynamic properties
• Defining JavaScript "methods"
• Adding Counter to RunScript

About the simplest embedding of Rhino possible is the RunScript example. All it does it read a script from the command line, execute it, and print a result.

Here's an example use of RunScript from a shell command line:

$ java RunScript 'Math.cos(Math.PI)'
-1
$ java RunScript 'function f(x){return x+1} f(7)'
8

Entering a Context

The code

Context cx = Context.enter();

Initializing standard objects

The code

Scriptable scope = cx.initStandardObjects(null);

Collecting the arguments

This code is standard Java and not specific to Rhino. It just collects all the arguments and concatenates them together.

String s = "";
for (int i=0; i < args.length; i++)
    s += args[i];

Evaluating a script

The code

Object result = cx.evaluateString(scope, s, "<cmd>", 1, null);

Print the result

The code

System.out.println(cx.toString(result));

Exit the Context

The code

Context.exit();

Use Java APIs

No additional code in the embedding needed! The JavaScript feature called LiveConnect allows JavaScript programs to interact with Java objects:

Using Rhino, JavaScript objects can implement arbitrary Java interfaces. There's no Java code to write--it's part of Rhino's LiveConnect implementation. For example, we can see how to implement java.lang.Runnable in a Rhino shell session:

js> obj = { run: function() { print('hi'); } }
[object Object]
js> obj.run()
hi
js> r = new java.lang.Runnable(obj);
[object Object]
js> t = new java.lang.Thread(r)
Thread[Thread-0,5,main]
js> t.start()
hi

The next example is RunScript2. This is the same as RunScript, but with the addition of two extra lines of code:

Defining Host Objects

Custom host objects can implement special JavaScript features like dynamic properties.

Counter example

The Counter example is a simple host object. We'll go through it method by method below.

It's easy to try out new host object classes in the shell using its built-in defineClass function. We'll see how to add it to RunScript later. (Note that because the java -jar option preempts the rest of the classpath, we can't use that and access the Counter class.) 

$ java -cp 'js.jar;examples' org.mozilla.javascript.tools.shell.Main
js> defineClass("Counter")
js> c = new Counter(7)
[object Counter]
js> c.count
7
js> c.count
8
js> c.count
9
js> c.resetCount()
js> c.count
0

The zero-argument constructor is used by Rhino runtime to create instances. For the counter example, no initialization work is needed, so the implementation is empty.

The class name is defined by the getClassName method. This is used to determine the name of the constructor.

Dynamic properties are defined by methods beginning with jsGet_ or jsSet_. The method jsGet_count defines the count property.

Defining JavaScript "methods"

Methods can be defined using the jsFunction_ prefix. Here we define resetCount for JavaScript.

Adding Counter to RunScript

Now take a look at the RunScript3 example. It's the same as RunScript except that the method ScriptableObject.defineClass uses a Java class to define the Counter "class" in the top-level scope: