Supporting the ServerJS Standard On Axiom Stack: First Steps

I've been following the ServerJS list on google groups for a while.  I'm excited about the emergence of javascript as a full-fledged modern language.   But it's sorely lacking in a lot of functionality we've come to take for granted in programming languages.  The ServerJS group has taken on the task of developing standard APIs and libraries to enable things like file system access, networking capabilities (although this is partially addressed by XMLHttpRequest) and a sensible, secure module system for pulling everything together.

There are several usable implementations of the early ServerJS standard available right now.  So I sat down this weekend to see if I could integrate one of them into Axiom Stack (the open source server-side javascript framework that powers this site.)  I chose Narwhal simply because the primary maintainer, Tom Robinson, is focusing on support for the Rhino JavaScript Engine.  Getting things up and running ended up being pretty straight forward, so I figured I'd outline things here.

On the surface Narwhal, and any other ServerJS compatible implementation, is just a library of javascript files that provide the standard APIs.  The underlying implementation relies on java packages though, which is why the Rhino engine is key.  Narwhal includes Rhino as a dependency and it also includes scripts for bootstraping the javascript environment in a JVM and loading the necessary js files.

That's all great for getting started with Narwhal, but Axiom Stack already provides the Rhino environment, and in fact it already provides a mechanism for loading js code into your application.  So my task was to find the merge point between Axiom modules and Narwhal packages.

Axiom Stack modules are pretty simple. Include your code in the modules folder under the Axiom install dir.  You need to follow a certain package structure that Axiom recognizes.  Then add the module name, which is just the name of the module folder, into your app.properties file.   It should look something like this:

AXIOM_R00T/
  modules/
     narwhal/
        Global/
           packages.js
            ...
            ...

And in your app.properties:

modules = narwhal

Now to figure out which Narwhal files to load.  Download the narwhal source from github.  Narwhal actually includes support for several javascript platforms including Rhino, Spidermonkey and v8.  Since I'm interested in the Rhino version, I'm checking things out in NARWHAL_ROOT/platforms/rhino/.  The lib/ folder has all kinds of good stuff, so I tried copying these files into my narwhal module Global/ folder.   That didn't work.  I got all kinds of awesome error messages about missing functions or variables.  So I read up a little and finally came across this helpful thread.

I think that for Jaxer and ASP, you can bypass bin/narwhal (which just finds itself and calls platforms/*/bin/narwhal-*), and you can bypass platforms/*/bin/narwhal-* (which just finds the engine and executes platforms/*/bootstrap.js) and go straight to platforms/*/bootstrap.js.

So it looks like we need to bootstrap the narwhal environment first.   But after that, the bootstrap file knows where everything else is.  So after some more futzing around and breaking things, I did what any self-respecting integration artist would do: I cheated.

All I needed was for Axiom Stack to load and execute that bootstrap file.  Axiom Stack loads whatever is in the modules/narwhal/Global/ folder.  So here's my setup:

AXIOM_ROOT/
   modules/
      narwhal/
         Global/
            bootstrap.js -> NARWHAL_ROOT/platforms/rhino/bootstrap.js

Yes, I simply symlinked the bootstrap file into the Axiom Stack file tree.  Almost there, but there's one more step.  The Narhwal loader looks for the "NARWHAL_HOME" environment variable to know where the install is.   So set this in your environment and restart Axiom Stack and you should be rocking and rolling.

Yeah, I know this is not ideal, and certainly wouldn't be acceptable for a production setup.  But hey, we're talking baby steps here.   This is pretty good for a couple of hours on a Saturday.  I've already got ideas on how make the integration a little more stable.  Hopefully in the future, Axiom Stack will be fully ServerJS compliant from the start.  Until then, check out Narwhal and make sure to give feedback to the group.