helma.org

Persistence API

Contents [hide]

Current efforts
Query API design

Prior Art

Current efforts

Hibernate wrapper for Helma NG and demo app by Robert Thurnher
Helma NG filestore module and demo app
Google App Engine datastore module and demo app (running on App Engine)
padded-ng is a CouchDB client by Jan-Felix Wittmann.
Liam Staskawicz is working on a Helma NG module for MongoDB.

Query API design

Collecting links of prior art and to collect more ideas on this.

Prior Art

MongoDB
- A Developer's Tour - Advanced Queries
- Developers' Guide - Searching and Retrieving
App Engine Datastore Low-level API - Query
DataMapper - http://datamapper.org/doku.php?id=docs
- Ruby-based ORM that provides nice modules that a variety of backends (rdbms and others) can mix in to provide common features like validation, lazy/eager loading, in addition to a nice query api
Mozilla ServerJS Relational Database Interface
Persevere JSONQuery

Middleware

Middleware is feature of the Helma NG webapp framework that provides a simple interface to inject additional code between the web server and the web application. Middleware uses the same calling conventions as web app actions: a function that takes a Request object as argument and returns a Response object.

Since middleware wraps the web application (and any middlware stacked upon it), it is in full control of how the request is processed.

Inspect and modify the request object before processing it further
Decide not to pass the request on, returning its own response instead
Inspect and modify the response obtained from the application

Middleware is configured in an exported Array called middleware in the app's config module. By convention, the webapp looks for a function called handleRequest in middleware modules.

The request argument contains a process method that is used to pass the request on in the middleware chain. Thus, a middleware implementation that just passes on the request might look like this:

  exports.handleRequest(req) {
    return req.process();
  }

Have a look at the modules/helma/middlware directory for the standard middleware currently shipping with Helma NG.

OverviewProposal

Skins & Macros
Models, ORM

Advanced Topics

Request, Response, Session
Url Mapping
Deployment
Other

Tutorials

The tutorial walks you through setting up helma and creating your first application.

Overview, if you already know another web framework and only need a highlevel overview.

If you only know the JavaScript browsers throw at you, you might want a Re-Introduction

Documentation

Detailed Reference of prototypes, properties and methods available in Helma. Keep this under your pillow.

Skins & Macros

Skin Rendering

Predefined Macros

Writing custom Macros

Advanced Skin Features - Subskins, Filters, Nested Macros, etc.

Models, ORM

Object Mappings - short enough to be used as a reference
Database Settings
Connecting to Mysql

FIXME reference for type.properties?

Advanced Topics

Many-To-Many-Relations

Programmatic Collections

Request, Response, Session

Response

Request

Session

Url Mapping

FIXME paragraph that quickly describes how this work in helma. self-explanatory if you already know models/orm

Deployment

Server & Application settings

Apache1 and mod_jk mostly applies to apache2 as well
Apache2 and mod_jk

Jetty
Jetty Url Rewrite

Other

Manage app manage your helma apps
Caching about the builtin object cache

Helma Book work in progress

Using the Source Code Repositories

Our SVN repositories are the place to get the latest source code of Helma 1.x, additional JS libraries and other Helma applications.

You can browse the SVN repository via WWW interface, where you will find sections for the Helma 1.x source code and various Helma applications and modules.

The latest source code of Helma NG, on the other hand, is available at Github.

Now you should have current Helma packages in helma/dist/ as follows:
helma/dist/helma-1.6.x-src.tar.gz helma/dist/helma-1.6.x-src.zip helma/dist/helma-1.6.x.tar.gz helma/dist/helma-1.6.x.zip

Building Helma NG from Git

Please see Helma NG's "Getting Started" for details.

Getting Started

This is a very short tutorial on how to install and start using Helma NG.

Contents [hide]

Installation
Using the shell
Running the demo app
Starting your own application

Installation

Helma requires Java 1.5 to run and uses Apache Ant as its build tool.

To get started with Helma NG either download the latest release or get the current snapshot from Github, either by clicking the download button or using the following git command:

git clone git://github.com/hns/helma-ng.git

Change to the helma-ng directory you just checked out and run ant it with the "jar" target:

ant jar

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

Using the shell

Once you have built the jar files you should be able to start the Helma NG shell. Just run the helma script in the bin directory without arguments:

/bin/helma

This should start a shell session with a helma> prompt. You can enter and evaluate any JavaScript expression. You can scroll through your session history using the <Up> and <Down> keys, hitting <Tab> will try to auto-complete your current input. Use the include, require, or import functions to load any Helma NG modules:

helma> include('helma/file'); helma> var file = new File('README.txt'); helma> file.open(); true helma> file.readln(); Helma NG helma> file.close(); true

Running the demo app

To run an actual web application simply pass the main file of the app to the helma command:

/bin/helma apps/demo/main.js

This will start the Helma NG demo app on port 8080. Enter the following URL in your browser to access the app:

http://localhost:8080/

You can also run an application and the shell at the same time by adding the -i or --interactive option before the application name:

/bin/helma -i apps/demo/main.js

Use the -h or --help flag for more information on available options.

Starting your own application

To start hacking on your own Helma application, use the admin/create script to create a new app:

/bin/helma admin/create [app directory]

If you don't pass the app directory on the command line the script will prompt you for it. Once the application has been created you can start it by running its main.js script:

/bin/helma appname/main.js

If you like Helma NG drop a note on the mailing list or the #helma channel on irc.freenode.net!

Running Rhino and Helma NG on Google App Engine

With Google's announcement of Java support 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).

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. This is somewhat in contradiction with what others have found, 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.

This article covers two options, one using the Helma NG webapp framework, and one using the Jack interface for JavaScript web applications.

Contents [hide]

Prerequisites: Installing App Engine SDK and Helma NG
Creating a new Web App project with the Eclipse plugin
Creating a new Web App project from the command line
Running Helma NG apps
Running Jack apps
Attachments

Prerequisites: Installing App Engine SDK and Helma NG

First, install the App Engine SDK for Java as described on the Google pages. 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.

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 or get the current snapshot from Github, either by clicking the download button or using the following git command:

git clone git://github.com/hns/helma-ng.git

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

ant jar
t
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:

lib/js.jar
lib/helma.jar
lib/log4j-1.2.15.jar

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.

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="*<a href="http://dev.helma.org/" class="wikiLink">/</a>.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:

lib/js.jar
lib/helma.jar
lib/log4j-1.2.15.jar

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 follow these steps:

Copy the modules directory from the Helma NG directory to war/WEB-INF so that the resulting directory is called WEB-INF/modules.
Copy the demo app from apps/demo to war/WEB-INF so that the resulting directory is called WEB-INF/demo. Note that the demo app contains a symbolic link, which is not supported by Google App Engine. Copying files with cp -rL will take care of dereferncing the link.
Copy or move the static directory from within the demo app two levels up to the war directory (war/static).
Edit WEB-INF/web.xml to look like the attached file, 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 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.

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 WEB-INF/web.xml.

For example, assuming you have the following simple Jack application in app/main.js:

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

You would then set the modulePath servlet init-parameter in web.xml to app, moduleName to main, and functionName to handler.

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

Attachments

name	type	size
web.xml	text/xml	1130 bytes

ng

This is a wiki space dedicated to Helma NG. Feel free to create new pages or edit existing ones. Helma NG consists of several components that can be used together or alone:

A compact JavaScript runtime environment based on Mozilla Rhino. It adds to Rhino a reloading module system that is compatible to the ServerJS Securable Module proposal.
An interactive shell with support for autocompletion and history.
A module library implemented in JavaScript, covering basic functionality such as extensions to the built-in objects, file I/O, logging, persistence, unit testing, client and server side HTTP support and web framework.

Contents [hide]

Overview
Resources
Recently edited pages

Overview

Resources

Recently edited pages

name	modified by	last modified
Persistence API	sleepnova	2009/06/25 19:20
Middleware	hannes	2009/06/18 20:20
Getting Started	hannes	2009/06/16 10:22
Running Rhino and Helma NG on Google App Engine	hannes	2009/06/16 10:20
Roadmap	hannes	2009/06/15 13:46
Tools	hannes	2009/05/20 00:59
Demo apps	hannes	2009/05/19 15:34
Shell	hannes	2009/05/19 14:11
Modules and Scopes	hannes	2009/05/13 12:53
jsdoc-toolkit_for_ng	marius	2009/05/08 14:57
modules	hannes	2009/04/30 15:21
helma.skin	hannes	2009/04/30 15:20
Modules Discussion	hannes	2009/04/30 11:34
Sandboxes	hannes	2009/04/03 18:19
helma.system	hannes	2009/04/03 18:19
helma.filestore	hannes	2009/02/20 23:00
Web Framework	hannes	2009/02/20 20:26
JavaScript Runtime	hannes	2009/02/06 11:12
Metamethods	hannes	2008/10/15 00:41
New Regexp based URL dispatching	hannes	2008/09/26 22:46

Roadmap

For a task-oriented view of the Helma NG roadmap see the trac roadmap page.

The next Helma NG release is 0.4. No release date has been set so far. We should probably look for a release date in July.

Some high-level goals for the 0.4 release:

Support for more future ServerJS APIs and modules such as system, file, binary.
Make Narwhal run on Helma NG (again)
JSDoc generated API documentation for modules and apps
Ability to run Helma NG as service
Ability to run untrusted code in Helma NG

marius

is a helma developer working in vienna

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:

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.
It's virtually impossible to produce a name collision, as each script lives in its own scope.
Since scripts live in their own scope, imported scripts are only visible to the scripts that imported them.

Contents [hide]

Implementation
Example
Further Reading

Implementation

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
    scope.load(script);
    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.

Example

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:

import("helma/database")

This makes the functions defined in helma/database.js available in the current scope as

  helma.database.getConnection()
  helma.database.Connection()
  helma.database.Query()

var db = require("helma/database")

This makes the functions defined in helma/database.js available in the current scope as

  db.getConnection()
  db.Connection()
  db.Query()

include("helma.database")

This makes the functions defined in helma/database.js available in the current scope as

  getConnection()
  Query()

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!

helma.org

Persistence API

Contents [hide]

Current efforts

Query API design

Prior Art

Middleware

OverviewProposal

Contents [hide]

Tutorials

Documentation

Skins & Macros

Models, ORM

Advanced Topics

Request, Response, Session

Url Mapping

Deployment

Other

Using the Source Code Repositories

Contents [hide]

Anonymous check-out from SVN

Checking-out an app or module from SVN

Building Helma 1.x from SVN

Building Helma NG from Git

Getting Started

Contents [hide]

Installation

Using the shell

Running the demo app

Starting your own application

Running Rhino and Helma NG on Google App Engine

Contents [hide]

Prerequisites: Installing App Engine SDK and Helma NG

Creating a new Web App project with the Eclipse plugin

Creating a new Web App project from the command line

Running Helma NG apps

Running Jack apps

Attachments

ng

Contents [hide]

Overview

Resources

Recently edited pages

Roadmap

marius

Modules and Scopes in Helma NG

Contents [hide]

Implementation

Example

Further Reading