Helma Documentation

Michael Platzer



Michael Jakl

Copyright (c) 2005 by Michael Platzer. This material is licensed under the Creative Commons Attribution-ShareAlike 2.0 Austria License. Terms and conditions for distribution can be found at Creative Commons: http://creativecommons.org/licenses/by-sa/2.0/at/deed.en.

Table of Contents

What is Helma?
Why Helma?
What is Helma really?
User's Guide
Setting up Helma
Obtaining Helma
General File Structure of Helma
Starting / Stopping Helma (Development Setup)
Server Setup
Setting up an Application
General File Structure of an Application
Rhino / Direct Scripting of Java
Helma's Host Objects
Helma Basics
Handling Form Data and File Uploads
DB Mapping
Object Modelling
Request Path Resolution
Rendering Framework
Session & User Management
Direct DB Connection
File Extension
FTP Extension
Image Extension
Mail Extension
XmlObject Extension
XmlRpc Client
XmlRpc Server
3rd party Extensions
Performance Tuning
Clustering Helma
Calling Helma from Commandline
Helma Core
Global Functions
Application Object 'app'
Hop Object
onXYZ() Event Functions
Request Object 'req'
Response Object 'res'
SessionObejct 'session'
Skin Object
Hello World
Address book
Mail Client


What is Helma?

Helma is a scriptable Java Web Application Server.

Basically the web application market can be divided into two segments. On the one hand, there are the server side (interpreted) scripting languages (like Perl and PHP), which are being supported and used by thousands of independent developers ever since the early days of the dynamic web. On the other hand, there are the web application servers (like JBoss, Tomcat, IBM Websphere), generally developed, supported and sold by large companies, requiring the in-depth knowledge of strictly-typed, compiled languages as Java or C#. With Helma being a "scriptable Application Server", it tries to bring together the benefits of both worlds.

Helma is a mature piece of software, which has been in production use for large, high-traffic news & community sites since years.

Helma is mainly being developed and maintained by Hannes Wallnoefer, a developer that is already well-known in the open-source community for providing the Java implementation of XML-RPC, which by now became part of the Apache foundation.

Why Helma?

So, what are the reasons to choose Helma in favour of another application platform?

  1. Applications are (generally) being scripted in JavaScript (resp. EcmaScript), a standardized, well-known, well-established, easy-to-learn scripting language.

  2. Any available Java-library can be made accessible for the scripting environment.

  3. Helma forces an object-orientated application design.

  4. Helma provides a transparent database-mapping, freeing the developer from hassling around, and polluting the code with SQL. As a side-effect, the relational database becomes substitutable at any point by any other JDBC-accessible database. Helma can even work without a relational database, by falling back to a file-based XML-database.

  5. Helma is Java. Scripted applications are compiled to Java, and server-side Java has proven to be quite fast and reliable, at least with the more recent Runtime Environments.

  6. Helma provides a smart caching mechanism, which minimizes the number of submitted select-queries to the database, by keeping recently-used objects in memory. This simple mechanism allows Helma to serve high-traffic sites, without developers even start thinking about performance tuning.

  7. Compared to other web application servers Helma is a light-weight (~1,5MB download), has a rather small memory footprint, and is fast on start-up.

  8. Helma is embeddable. It can be used to write a web frontend to existing Java applications.

  9. If one Helma-server proves to be not sufficient for the request load, more servers can be easily clustered together. Again without requiring developers to rewrite their applications.

  10. Scripted code is compiled to Java instantaneously, i.e. as soon as the modified source file is saved to disk. No need for developers to "compile and run" the whole application, before they can see their modifications in action.

  11. Helma provides a smart templating mechanism, which forces a strict separation of content, logic and presentation.

  12. Helma comes along with numerous extensions, which are usually required for developing web applications. These allow developers to easily

    1. send emails

    2. and write text-files

    3. and manipulate images

    4. a XML-RPC-client and -server

    5. access databases

    6. to a FTP-server

    7. generate Flash-Files

    8. much more.

  13. Helma provides transparent session management, i.e. developers are freed from the task to assign requests to sessions.

  14. Developers can easily generate clear, intuitive, easy-to-remember, search-engine-friendly URLs.

  15. A scheduling mechanism is integrated into Helma, which allows the automated execution of scripts at any given time.

  16. Helma is open-source, and comes with a liberal BSD style license. Its source-code can be studied, modified (and also distributed) by anybody who wishes to. No license costs are being charged, neither for private, nor for commercial use. All the advantages of open-source software apply to Helma. See the License itself: http://helma.org/download/license/.

What is Helma really?

The technology-affine reader might wonder by now, what Helma really is. The Helma distribution consists of multiple Java libraries, most of them provided by third-party, all having their own specific task.

These libraries are:


The core of Helma, which brings together all of the following libraries and is in charge of Application Management, Code loading, Request Path Resolution, Session Management, DB mapping, Caching, Templating, Scheduling, and more. Take a look at the JavaDocs (or the source code) to get an in-depth view of Helma.


The JavaScript to Java compiler, which is actively developed by the Mozilla foundation. Read more about Rhino at http://www.mozilla.org/rhino.


The Jetty Server, which is also integrated with JBoss for example, provides a powerful and stable web server, as well as the AJP13-connection to integrate Helma with (nearly) any other web server (via the mod_jk module provided by the Apache foundation). See http://jetty.mortbay.org.


An image-manipulation library provided by Sun.


Providing a XML- and HTML-DOM-Parser.


Sun's official JavaMail library.


a XML-SAX-Parser.


Providing (among other things) a Java FTP-client.


Providing the Java Servlet Api.


Implementation of a XML-RPC-client and server.


File Upload Library. See http://jakarta.apache.org/commons/fileupload/.