Helma Logo
main list history
previous version  overview  next version

Version 27 by hannes on 16. September 2009, 17:02

#MARKDOWN

With Google's [announcement][1] of [Java support][2] for App Engine there is all of a sudden a very attractive new option for hosting Java based web applications. Of course my first impulse was to check if it would run [Rhino] and Helma NG (I had little hopes for Helma 1 as it runs a lot of background threads and relies heavily on relational or file based database backends, both of which are not available on App Engine).

[1]: http://googleappengine.blogspot.com/2009/04/seriously-this-time-new-language-on-app.html
[2]: http://code.google.com/appengine/docs/java/overview.html
[rhino]: http://www.mozilla.org/rhino/

To my surprise, Rhino works perfectly out of the box, and I only had to make a few changes to Helma NG to get the demo app [running on App Engine][3]. This is somewhat in contradiction with what [others have found][ola], and I discovered only later that I was partly lucky for not stomping on any SecurityExceptions, but on the other hand it's by virtue of Rhino not doing a lot of tricks under the hood, and Helma NG doing all its file reading through a unified [resource framework][4].

[3]: http://helma-ng.appspot.com/
[ola]: http://olabini.com/blog/tag/gae/
[4]: http://github.com/hns/helma-ng/tree/master/src/org/helma/repository

This article covers two options, one using the Helma NG webapp framework, and one using the *Jack|http://github.com/tlrobinson/jack/tree/master* interface for JavaScript web applications.

### Prerequisites: Installing App Engine SDK and Helma NG

First, install the App Engine SDK for Java as described on the [Google pages][gae-install]. Whether you use the Eclipse plugin or the command line SDK shouldn't make a difference. I'm using Eclipse, but things should work in a similar fashion with the command line SDK.

[gae-install]: http://code.google.com/appengine/docs/java/gettingstarted/installing.html

Next, you need Helma NG, which is effectively Rhino with a thin layer of server-related functionality on top. Helma NG currently comes with its own copy of Rhino as we are using some experimental JS 1.8 features, but this may change as soon as these features are included in a Rhino release.

You can [download the latest release][download] or get the current snapshot [from Github][github], either by clicking the download button or using the following git command:

[download]: http://github.com/hns/helma-ng/downloads
[github]: http://github.com/hns/helma-ng/tree/master

<tt style="font-weight:bold;color:#d33;">git clone git://github.com/hns/helma-ng.git</tt>

You need [Apache Ant][ant] to build Helma NG. Change to the helma-ng directory you just checked out and run ant it with the "jar" target:

[ant]: http://ant.apache.org/

<tt style="font-weight:bold;color:#d33;">ant jar</tt>

If this worked then you should now have a file called lib/helma.jar.

### Creating a new Web App project with the Eclipse plugin

Once you have everything in place, create a new, empty App Engine application. Use the new project wizard and select "Web Application Project" in the Google category. This will ask you for a project name and a package name. The package name doesn't matter unless you plan to write Java code, but it is required so just enter anything.

The new project should have two subdirectories, "src" and "war". Again, the src dir is only relevant for Java code, as we'll put our JavaScript code directly in war/WEB-INF and our jar files in war/WEB-INF/lib.

Next, copy over some jar files from the Helma NG lib directory to the war/WEB-INF/lib of your project. You'll probably need the following:

* <tt style="font-weight:bold;color:#d33;">lib/js.jar</tt>
* <tt style="font-weight:bold;color:#d33;">lib/helma.jar</tt>
* <tt style="font-weight:bold;color:#d33;">lib/log4j-1.2.15.jar</tt>

App Engine has its own web server of course, so you don't need the jetty or servlet jar files.

From here, you have two options: Run an app using the Helma NG webapp framework, or one using the [Jack] interface.

[jack]: http://github.com/tlrobinson/jack/tree/master

### Creating a new Web App project from the command line

From the SDK directory, copy demos/new_project_template and rename it to your application's name (say "Demo").

Open Demo/build.xml, locate the property appengine.sdk and modify it so that it points to the path of the SDK root directory on your machine.

Also add the following:

    <target name="copyjars"
          description="Copies the App Engine JARs to the WAR.">
      <copy todir="${war.dir}/WEB-INF/lib"
          flatten="true">
        <fileset dir="${appengine.sdk}/lib/user">
          <include name="\*\*/*.jar" />
        </fileset>
      </copy>
    </target>

Again in build.xml locate the "war" target and add a dependency on the "copyjars" target so that it looks like:

    <target name="war" depends="enhance,copyjars"
          description="Assemble the application directory">

Run "ant" in the same directory as "build.xml" so that the WEB-INF directory will be created.

Next, copy over some jar files from the Helma NG lib directory to the www/WEB-INF/lib of your project. You'll probably need the following:

* <tt style="font-weight:bold;color:#d33;">lib/js.jar</tt>
* <tt style="font-weight:bold;color:#d33;">lib/helma.jar</tt>
* <tt style="font-weight:bold;color:#d33;">lib/log4j-1.2.15.jar</tt>

App Engine has its own web server of course, so you don't need the jetty or servlet jar files.

From here, you have two options: Run an app using the Helma NG webapp framework, or one using the [Jack] interface.

### Running Helma NG apps

To run the Helma NG *demo application|http://helma-ng.appspot.com/* follow these steps:

1. Copy the modules directory from the Helma NG directory to war/WEB-INF so that the resulting directory is called <tt style="font-weight:bold;color:#d33;">WEB-INF/modules</tt>.

2. Copy the demo app from apps/demo to war/WEB-INF so that the resulting directory is called <tt style="font-weight:bold;color:#d33;">WEB-INF/demo</tt>. Note that the demo app contains a symbolic link, which is not supported by Google App Engine. Copying files with <tt style="font-weight:bold">cp -rL</tt> will take care of dereferncing the link.

3. Copy or move the static directory from within the demo app two levels up to the war directory (war/static).

4. Edit <tt style="font-weight:bold;color:#d33;">WEB-INF/web.xml</tt> to look [like the attached file](http://dev.helma.org/static/files/3318/web.xml), or just download and overwrite the file.

5. Edit <tt style="font-weight:bold;color:#d33;">WEB-INF/appengine-web.xml</tt> to look [like the attached file](http://dev.helma.org/static/files/3318/appengine-web.xml), or just download and overwrite the file.

That's it - save all your changes and click on the green Run button in Eclipse or run the dev_appserver.sh script to start the development server. If everything worked as planned you should be able to access the [demo app](http://helma-ng.appspot.com/) on http://localhost:8080/.

### Running Jack apps

Helma NG uses [Jack] to as web application connector, so you are not bound to use the Helma webapp infrastructure. If you prefer, you can use Helma NG as a container for Jack applications fully compatible with the [ServerJS Securable Modules proposal](https://wiki.mozilla.org/ServerJS/Modules/SecurableModules).

The setup is much the same as with the Helma NG demo application, only that you point the JackServlet to your own Jack web appliction in <tt style="font-weight:bold;color:#d33;">WEB-INF/web.xml</tt>.

For example, assuming you have the following simple Jack application in <tt style="font-weight:bold;color:#d33;">app/main.js</tt>:

    function handler(env) {
      return [200, {"Content-Type": "text/plain"}, ["Hello World!"]];
    }

You would then set the <tt style="font-weight:bold;color:#d33;">modulePath</tt> servlet init-parameter in [web.xml](http://dev.helma.org/static/files/3318/web.xml) to <tt style="font-weight:bold;">app</tt>, <tt style="font-weight:bold;color:#d33;">moduleName</tt> to <tt style="font-weight:bold;">main</tt>, and <tt style="font-weight:bold;color:#d33;">functionName</tt> to <tt style="font-weight:bold;">handler</tt>.

After starting the development server you should be able to access your Jack app at http://localhost:8080/.

### Attachments

<% this.attachments %>

     removed
     added