Setting up an Application

apps.properties

[HelmaHome]/apps.properties defines active applications.

Assuming that Helma is run by the class helma.main.Server (which is the case if Helma is started via one of the start scripts, and is not embedded for example into Tomcat), the list of active applications is defined by the file [HelmaHome]/apps.properties. Each line in that file, that is neither a comment (i.e. starts with a '#') nor contains a period '.', corresponds to an active application. For each such defined application, it is possible to specify further (optional) parameters.

So, in order to start a new application, you just need to add a new line to apps.properties, containing the application name. This may also be done while Helma is running. Helma detects changes to its property-files automatically, and applies them immediately. In order to stop a running application, the line containing the application name needs to be commented out, or removed. The defined parameters can be left untouched.

# The next line tells Helma to start/run an  
# application named 'appname' 
appname 
 
# The following lines list the available  
# optional parameters, together with their 
# default settings. 
appname.appdir = apps/appname 
appname.repository.0 = apps/appname 
appname.repository.0.implementation = \  
  helma.framework.repository.FileRepository 
appname.dbdir = db/appname 
appname.mountpoint = /appname 
appname.static 
appname.staticMountpoint 
appname.staticHome = index.html,index.htm 
appname.staticIndex = false 
appname.protectedStatic 
appname.uploadLimit = 4096 
appname.uploadSoftfail = false 
appname.cookieDomain 
appname.sessionCookieDomain = HopSession 
appname.protectedSessionCookie = true
appdir

Defines the location of the source code repository of that application. Can be either relative (to [HelmaHome]), or absolute. The default location is [HelmaHome]/apps/[appname]. We will refer to this directory as [AppDir] in this document.

repository.X, repository.X.implementation

Alternatively to specifying a single code repository, it is possible to define multiple repositories. See the online documentation for details: http://helma.org/development/rfc/77606/ (FIXME).

dbdir

Defines the location of the internal XML-based database used by Helma for that application. Even if all HopObjects are mapped to a relational database, this directory is needed for certain files. Can be either relative (to [HelmaHome]), or absolute. The default location is [HelmaHome]/db/[appname]. We will refer to this directory as [DbDir] in this document.

mountpoint

This setting tells Helma which web requests should be handled by that application. By default this is /appname, i.e. all requests to http://localhost:8080/appname (assuming the HTTP_PORT 8080 is enabled) are handled by that application. It is also possible to set this value just to '/', so that the name of the application is not contained in the URL anymore.

Hint: For Apache/mod_jk/mod_rewrite/Helma-Setups it is common practice to mount applications at /helma/appname, so that just a single configuration line is required to tell mod_jk what kind of requests should be forwarded to Helma (i.e. those starting with /helma).

static

Helma, resp. Jetty can also serve static content. By default this is disabled, but can be enabled by specifying 'static'. This setting expects the absolute or relative (with respect to [HelmaHome]) path to a directory, from which static content should be served.

staticMountpoint

If the serving of static content is enabled, the URL for static content starts with the mountpoint of the application with '/static' being appended to that (e.g. http://localhost:8080/appname/static). By specifying this setting, it is possible to change that mountpoint.

staticHome

Analog to Apache's DirectoryIndex-directive it is possible to tell Jetty which file to serve, if a static directory is requested. This can be a comma-separated list of multiple filenames. The default value is 'index.html,index.htm'.

staticIndex

By setting this to 'true' directory-listings are returned by Jetty. Similar to Apache's mod_autoindex. The default behaviour is to not return such listings.

protectedStatic

Helma includes methods to serve static content from the scripting environment (see res.forward). That way it is possible to have some application code being processed (for example to check for access-rights), before actually serving that content. In order to enable this feature, the protectedStatic-setting has to be set to the location of a directory (either absolute, or relative to [HelmaHome]) from which that content is served.

uploadLimit

Specifies the maximum size for uploaded files in Kilobyte. The default is 1024, i.e. 1MB.

uploadSoftfail

Determines how an upload, that exceeds the uploadLimit should be handled. If this is explicitly set to "true", then Helma will not generate an immediate error response, and just sets the property helma_upload_error in the req.data object, which indicates that an error has occured. Otherwise a non-customizable HTTP error with status code 413 will be thrown.

cookieDomain

By default all cookies that are sent to the Client with res.setCookie are assigned to the same domain as the request went to. If cookieDomain is set, and cookieDomain is a substring of the requested domain, cookies are assigned to that cookieDomain. This has the advantage, that the same cookies can be shared across all sub-domains, by setting the cookieDomain to something like '.domain.tld'.

sessionCookieName

By default Helma assigns requests to sessions according to a session-cookie named 'HopSession'. By specifying the setting sessionCookieName, it is possible to tell Helma to use another name for that cookie.

protectedSessionCookie

By default Helma binds the generated session cookie to the first three octets of the client's ip-address. This mechanism offers some protection against possible cross-site-scripting attacks ( http://en.wikipedia.org/wiki/Cross_site_scripting), but on the other hand can make Helma session's mechanism unusable for some users (e.g. users with a round-robin proxy setup). This mechanism can be disabled by setting this property to 'false'.

As soon as the application is started, Helma will look for the [AppDir], and checks whether it already exists and whether it contains at least one file. If this is not the case, Helma will create four directories: Global, Root, HopObject and User. Similar, the [DbDir] will be created, if it does not exist yet.