Helma Logo
main list history

Version 8 by hannes on 03. April 2009, 18:19

9One cool new feature the helma.system module provides is the createSandbox() function to create *JavaScript sandboxes|Sandbox*sandboxes|Sandboxes*. 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.

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

9One 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.
10
11The 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:
12
13  include("helma/system");
14  var sandbox = createSandbox("some/dir", {require: require});
15  sandbox.runScript("test.js");
16
17The 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.
18
19  var classShutter = function(classname) { return false; };
20  var sandbox = createSandbox('some/dir', {require: require},
21                              classShutter, true);
22
23Note 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.

Version 6 by hannes on 03. April 2009, 18:16

5Command 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 unmodifyable 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.
6
7=== Sandboxes
8
9One cool new feature the helma.system module provides is the createSandbox() function to create *JavaScript sandboxes*. 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.
10
11The 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:
12
13  include("helma/system");
14  var sandbox = createSandbox("some/dir", {require: require});
15  sandbox.runScript("test.js");
16
17The 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.
18
19  var classShutter = function(classname) { return false; };
20  var sandbox = createSandbox('some/dir', {require: require},
21                              classShutter, true);
22
23Note 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.

Version 5 by hannes on 20. February 2009, 21:30

3=== Setting up Host objectsCommand line arguments
5Command 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 unmodifyable <a href="http://www.advogato.org/article/1001.html">java.util.List</a>, althought we may expose this as JavaScript array in the future.
6
7=== Repositories and Resources
8
9FIXME: addRepository(), getRepositories()
10
11=== Host Objects
12
10=== Scripting Extending Java classesClasses
25=== Setting the Rhino optimization levelOptimization Level

Version 4 by hannes on 20. February 2009, 21:21

5By 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. The helma.system module provides a utility method called <code>initWebApp()</code> that sets up the *host objects|Helma NG Core API* used for web applications.
23
24=== Managing callbacks
25
26helma.system provides *addCallback(), removeCallback(), and invokeCallback() methods|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/modules/helma/system.js#L34* to register, remove and invoke *callbacks*.

Version 3 by hannes on 26. September 2008, 12:44

1The *helma.rhino system module|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/modules/helma/rhinoorg/trac/helma/browser/helma-ng/trunk/modules/helma/system.js* provides methods to access the Helma NG Rhino scripting engine.
5By 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. The helma.rhino system module provides a utility method called <code>initWebApp()</code> that sets up the *host objects|Helma NG Core API* used for web applications.
7You can also register *your own host objects|http://www.mozilla.org/rhino/tutorial.html#javaScriptHostObjects* using the helma.rhinosystem.addHostObject() method, passing the host object java class as only argument.
13The helma.rhinosystem.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.
15  var HashMap = helma.rhinosystem.extendJavaClass(java.util.HashMap);
26helma.rhino system provides *addCallback(), removeCallback(), and invokeCallback() methods|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/modules/helma/rhinoorg/trac/helma/browser/helma-ng/trunk/modules/helma/system.js#L34* to register, remove and invoke *callbacks*.
30The helma.rhinosystem.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.
36The rhino 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.

Version 2 by hannes on 16. May 2008, 11:30

5By default, Helma NG hasn't got does not contain any web specific custom host classesobjects. This is useful to allow makes sense when using Helma NG in other contexts than the typical web application. The helma.rhino module provides a utility method called <code>initWebApp()</code> that sets up the *host objects|Helma NG Core API* used for web applications.

Version 1 by hannes on 16. May 2008, 11:28

1The *helma.rhino module|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/modules/helma/rhino.js* provides methods to access the Helma NG Rhino engine.
3=== Setting up Host objects
4
5By default, Helma NG hasn't got any web specific host classes. This is useful to allow using Helma NG in other contexts than the typical web application. The helma.rhino module provides a utility method called <code>initWebApp()</code> that sets up the *host objects|Helma NG Core API* used for web applications.
6
7You can also register *your own host objects|http://www.mozilla.org/rhino/tutorial.html#javaScriptHostObjects* using the helma.rhino.addHostObject() method, passing the host object java class as only argument.
8
9=== Scripting Java classes
10
11Helma NG allows you to add methods and properties to existing Java classes.
12
13The helma.rhino.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.
14
15  var HashMap = helma.rhino.extendJavaClass(java.util.HashMap);
16  HashMap.prototype.dump = function() { res.write(this); }
17
18Note 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.
19
20Note 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.
21
22You 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.
23
24=== Managing callbacks
25
26helma.rhino provides *addCallback(), removeCallback(), and invokeCallback() methods|http://dev.helma.org/trac/helma/browser/helma-ng/trunk/modules/helma/rhino.js#L34* to register, remove and invoke *callbacks*.
27
28=== Setting the Rhino optimization level
29
30The helma.rhino.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.
31
32Note 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.
33
34=== Going further
35
36The rhino 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.