Helma Logo
main list history

Modules and Scopes in Helma NG

The javascript import features in Helma NG try to loosely imitate the semantics of python's import statement in order to allow applications to be written in a truly modular way. The magic of python's import statement is that a script never has to do anything special in order to avoid name clashes with other scripts, because every script lives in its one top level scope by default.

To sum it up:

  1. You don't have to use any special Javascript syntax to denote a namespace. Every script is by its nature a separate scope, assigned to a namespace by the script that imported it.
  2. It's virtually impossible to produce a name collision, as each script lives in its own scope.
  3. Since scripts live in their own scope, imported scripts are only visible to the scripts that imported them.


Helma NG implements this by using a separate top-level scope for each loaded script file, using a shared top-level scope as prototype. A simplistic implementation of most of the behaviour described above in the Rhino shell may look like this:

  // set reference to global object
  var __global__ = __global__ || this;
  function include(script, as) {
    var scope = new Object();
    scope.__parent__ = null;
    scope.__proto__ = __global__;
    // scope is now a top level scope that inherits 
    // from the global, shared top level scope
    this[as] = scope;

Of course, Helma NG also takes care of script reloading and stuff, and the shared module scope is really a per-thread scope that uses a really-shared scope for the really-shared stuff.


Suppose there is a Javascript file called helma/database.js with the following content:

  function getConnection(...) {
  function Connection(...) {
  function Query(...) {

Then consider the following statements in another script file:

This makes the functions defined in helma/database.js available in the current scope as
var db = require("helma/database")
This makes the functions defined in helma/database.js available in the current scope as
This makes the functions defined in helma/database.js available in the current scope as

Note that the functions in helma/database.js do not care in which namespace they are loaded. They only see what is defined in their local file, and in the global scope shared by all modules. The scope that loaded the module is absolutely invisible to the loaded module! Also note that the getConnection() function in the last example can still access the Connection() constructor although it's not included in the importFromModule(). That's the power of closures!

Further Reading

There is a newer article about the background and history of the Helma NG module system as well as a more up-to-date technical article.

Links to this page: Background and History


#1 by maks at 2008/04/17 03:56

This looks very nice, but it doesn't seem to be in helma2 svn trunk yet (as of 17/4/2008)?

#2 by matthias at 2008/04/24 18:58

can you explain where the modules have to / may be located, and how i can influence that. thanks.

#3 by hannes at 2008/04/24 20:22

Matthias: have a look at the README.txt. Quoting from there:

Helma first tries to resolve the path relative to the location of the module calling this method. If that fails, it looks for the resource in the repository path, which usually consists of the current directory (shell) or app directory (web apps) and the modules directory.

The module path can be set using the helma.modulepath property:

  java -Dhelma.modulepath=myapp,mylibs,modules -jar shell.jar
#4 by matthias at 2008/04/25 03:53

Thanks for the pointer. I guess that this will be more elegant in a future version (no shell parameter)

Another comment: I would prefer importModule("helma/database") over importModule("helma.database") -> this would resolve the problem, that you can't have dots in file- or foldernames (which is common for libraries)

And a question / request: Wildcards to load whole folders: Have you any plans / ideas how to support this?

#5 by hannes at 2008/04/25 12:24

Yes, it would be possible to use slashes as path separator in importModule. I'd then prefer to also include the .js suffix: importModule('helma/database.js'). The idea with the dot is that it is platform agnostic, plus it's the way python does it. But I think slashes are supported/recognized enough even on windows these days :-)

Regarding wildcards: they're supported as second argument to importFromModule, i.e. to import all properties from the loaded module into the current scope. They currently aren't supported for the other import functions, i.e. to import all modules from a given directory.