Helma Logo
main list history
previous version  overview  next version

Version 7 by hannes on 03. April 2009, 18:18

The *helma.system module|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/modules/helma/system.js* provides methods to access the Helma NG scripting engine.

=== Command line arguments

Command line arguments passed to the main script can be accessed through the <code>args</code> property of the helma.system module. This is currently an instance of an unmodifiable <a href="http://www.advogato.org/article/1001.html">java.util.List</a>, althought we may expose this as JavaScript array in the future.

=== Sandboxes

One cool new feature the helma.system module provides is the createSandbox() function to create *JavaScript sandboxes*sandboxes|Sandbox*. It allows you to set up an isolated JavaScript environment with its own module search path and global object. Optionally, you can inject global properties, restrict access to Java objects using a ClassShutter, and seal the global object.

The following code shows how to set up a sandbox with the directory <tt>some/dir</tt> as only module path and pass it the require() function from our host environment:

  var sandbox = createSandbox("some/dir", {require: require});

The createSandbox() function tries to evaluate a file called <tt>global.js</tt> to initialize the sandbox's global object. Optionally, the global object can be sealed after global.js has been run. The following code shows how to do that and also creates a sandbox that prevents any access to java objects.

  var classShutter = function(classname) { return false; };
  var sandbox = createSandbox('some/dir', {require: require},
                              classShutter, true);

Note that the require function we pass to the sandbox is not affected by the ClassShutter since it is defined in the outer trusted host environment.

=== Repositories and Resources

FIXME: addRepository(), getRepositories()

=== Host Objects

By default, Helma NG does not contain any custom host objects. This makes sense when using Helma NG in other contexts than the typical web application.

You can also register *your own host objects|http://www.mozilla.org/rhino/tutorial.html#javaScriptHostObjects* using the helma.system.addHostObject() method, passing the host object java class as only argument.

=== Extending Java Classes

Helma NG allows you to add methods and properties to existing Java classes.

The helma.system.extendJavaClass() takes a java class as argument and returns an extended java class wrapper. You can add Javascript functions to the java class like it was a Javascript constructor, using the class wrapper's prototype property.

  var HashMap = helma.system.extendJavaClass(java.util.HashMap);
  HashMap.prototype.dump = function() { res.write(this); }

Note that while the class wrapper works as constructor for the extended class, the added functions and properties are available also on objects created using the standard java constructor and even objects created and returned from java code. The Helma NG object wrapper takes care of this.

Note that this is different from Rhino's *JavaAdapter|http://www.mozilla.org/rhino/scriptjava.html#extending*. JavaAdapter allows you to create new java classes in javascript, extending existing classes and implementing existing interfaces. The Helma NG java class extension feature allows you to add scripted functions to existing java classes without creating a new class.

You can also script java superclasses and interfaces. However, Helma NG currently does not implement extended class merging or chaining. In other words, if both java.util.HashMap, java.util.Map and java.lang.Object classes are extended, java instances will only have the "nearest" extension: HashMap instances will only have the extended properties of java.util.HashMap, TreeMap objects those of java.util.Map, and ArrayList those of java.lang.Object.

=== Setting the Optimization Level

The helma.system.setRhinoOptimizationLevel() method allows you to set the Rhino optimization level. Accepted values are integer numbers between -1 and 9. The default level is 0 and implements basic Javascript to Java bytecode compilation. Level -1 disables the bytecode compiler and sets Rhino to interpreter mode, which is required for some features such as *continuations*. Levels 1 to 9 add some optimizations that may or may not be detrimental to your health.

Note that Helma NG can run in both Java-compiled and interpreted mode in the same application, so you can call this on a per-request basis in the onInvoke *callback*. Also note that setting the optimization level in the 0..9 range does not cause scripts that have already been compiled and cached to be recompiled.

=== Going further

The system module provides utility methods getRhinoContext() and getRhinoEngine() to access the current *Rhino Context|http://www.mozilla.org/rhino/apidocs/org/mozilla/javascript/Context.html* and *Rhino Engine|http://dev.helma.org/static/ng/api/org/helma/javascript/RhinoEngine.html* instances. These classes provide a lot of Javascript related functionality that can be easily used from application code.