Serialization


Beginning with Rhino 1.5 Release 3 it is possible to serialize JavaScript objects, including functions and scripts. However,  serialization of code in compilation mode has some significant limitations.. Serialization provides a way to save the state of an object and write it out to a file or send it across a network connection.
 

Simple serialization example

The Rhino shell has two new top-level functions, serialize and deserialize. They're intended mainly as examples of the use of serialization:
$ java org.mozilla.javascript.tools.shell.Main
js> function f() { return 3; }
js> serialize(f, "f.ser")
js> quit()

$ java org.mozilla.javascript.tools.shell.Main
js> f = deserialize("f.ser")

function f() {
    return 3;
}

js> f()
3
js>

















Here we see a simple case of a function being serialized to a file and then
read into a new instance of Rhino and called. 




Rhino serialization APIs

Two new classes, ScriptableOutputStream and ScriptableInputStream, were introduced
to handle serialization of Rhino classes. These classes extend ObjectOutputStream
and ObjectInputStream respectively. Writing an object to a file can be done
in a few lines of Java code:


FileOutputStream fos = new FileOutputStream(filename);
ScriptableOutputStream out = new ScriptableOutputStream(fos, scope);
out.writeObject(obj);
out.close();


Here filename is the file to write to, obj is the object or function to
write, and scope is the top-level scope containing obj. 


Reading the serialized object back into memory is similarly simple:


FileInputStream fis = new FileInputStream(filename);
ObjectInputStream in = new ScriptableInputStream(fis, scope);
Object deserialized = in.readObject();
in.close();


Again, we need the scope to create our serialization stream class. 


So why do we need these specialized stream classes instead of simply using
ObjectOutputStream and ObjectInputStream? To understand the answer we must
know what goes on behind the scenes when Rhino serializes objects. 


How Rhino serialization works

By default, Java serialization of an object also serializes objects that
are referred to by that object. Upon deserialization the initial object and
the objects it refers to are all created and the references between the objects
are resolved. 



However, for JavaScript this creates a problem. JavaScript objects contain
references to prototypes and to parent scopes. Default serialization would
serialize the object or function we desired but would also serialize Object.prototype
or even possibly the entire top-level scope and everything it refers to!
We want to be able to serialize a JavaScript object and then deserialize
it into a new scope and have all of the references from the deserialized
object to prototypes and parent scopes resolved correctly to refer to objects
in the new scope. 



ScriptableOutputStream takes a scope as a parameter to its constructor. If
in the process of serialization it encounters a reference to the scope it
will serialize a marker that will be resolved to the new scope upon deserialization.
It is also possible to add names of objects to a list in the ScriptableOutputStream
object. These objects will also be saved as markers upon serialization and
resolved in the new scope upon deserialization. Use the addExcludedName method
of ScriptableOutputStream to add new names. By default, ScriptableOutputStream
excludes all the names defined using Context.initStandardObjects.



If you are using Rhino serialization in an environment where you always define,
say, a constructor "Foo", you should add the following code before calling
writeObject:


out.addExcludedName("Foo");
out.addExcludedName("Foo.prototype");

This code will prevent Foo and Foo.prototype from being serialized and will
cause references to Foo or Foo.prototype to be resolved to the objects in
the new scope upon deserialization. Exceptions will be thrown if Foo or Foo.prototype
cannot be found the scopes used in either ScriptableOutputStream or ScriptableInputStream.

 


Rhino serialization in compilation mode

 Serialization works well with objects and with functions and scripts in
interpretive mode. However, you can run into problems with serialization
of compiled functions and scripts:


$ cat test.js
function f() { return 3; }
serialize(f, "f.ser");
g = deserialize("f.ser");
print(g());
$ java org.mozilla.javascript.tools.shell.Main -opt -1 test.js
3
$ java org.mozilla.javascript.tools.shell.Main test.js
js: uncaught JavaScript exception: java.lang.ClassNotFoundException: c1


The problem is that Java serialization has no built-in way to serialize
Java classes themselves. (It might be possible to save the Java bytecodes
in an array and then load the class upon deserialization, but at best that
would eat up a lot of memory for just this feature.) One way around this
is to compile the functions using the jsc tool: 


$ cat f.js
function f() { return 3; }
$ java -classpath js.jar org.mozilla.javascript.tools.jsc.Main f.js
$ cat test2.js
loadClass("f");
serialize(f, "f.ser");
g = deserialize("f.ser");
print(g());
$ java -classpath 'js.jar;.' org.mozilla.javascript.tools.shell.Main test2.js
3


 Now the function f is compiled to a Java class, but that class is
then made available in the classpath so serialization works. This isn't that
interesting an example since compiling a function to a class and then loading
it accomplishes the same as serializing an interpreted function, but it becomes
more relevant if you wish to serialize JavaScript objects that have references
to compiled functions. 


  



 back to top