Reference

Helma Core

Global Functions

This sections documents methods available in a global context. For further details also see the JavaDocs for helma.scripting.rhino.GlobalObject.

authenticate(String user, String pwd) returns Boolean

Authenticates a user against a standard Unix password file. Returns true if the provided credentials match an according entry in the files [AppDir]/passwd or [HelmaHome]/passwd. The stored passwords in these files must be either encrypted with the unix crypt algorithm, or with the MD5 algorithm. The Apache web server provides the utility tool ' htpasswd' to generate such password files.

createSkin(String str) returns SkinObject

Creates a SkinObject from the passed String. The returned object can be passed to the global functions renderSkin, resp. renderSkinAsString. Also see the reference on the SkinObject.

encode(String str) returns String

Performs the following string manipulations:

  • All line breaks (i.e. carriage returns and line feeds) are replaced with <br /> tags.

  • All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.

  • Existing markup tags are being encoded.

and returns the modified string.

encodeForm(String str) returns String

Performs the following string manipulations:

  • All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.

  • Existing markup tags are being encoded.

and returns the modified string.

encodeXml(String str) returns String

Performs the following string manipulations:

  • All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.

  • Existing tags, single and double quotes, as well as ampersands are being encoded.

  • Some invalid XML characters below '0x20' are removed.

and returns the modified string.

format(String str) returns String

Performs the following string manipulations:

  • All line breaks (i.e. carriage returns and line feeds) are replaced with <br /> tags, with the exception of line breaks that follow certain block tags (e.g. table, div, h1, ..).

  • All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.

and returns the modified string.

formatParagraphs(String str) returns String

Performs the following string manipulations:

  • All line breaks (i.e. carriage returns and line feeds) are replaced with <br /> tags, with the exception of line breaks that follow certain block tags (e.g. table, div, h1, ..).

  • Paragraphs are detected, and surrounded with <p> tags. Two following line breaks are considered to indicate a paragraph.

  • All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.

and returns the modified string.

getDBConnection(String dbsource) returns DatabaseObject

Connects to a relational database, and returns a DatabaseObject representing that connection. The passed string must match one of data sources being defined in [AppDir]/db.properties, or an error will be thrown. Also see the reference on the DatabaseObject. (FIXME LINK)

getHtmlDocument(Object src) returns org.apache.html.dom.HTMLDocumentImpl

Tries to parse an object to a XML DOM tree using Xerces' HTML parser (nekohtml). The argument must be either a URL, a piece of XML, an InputStream or a Reader. Returns an instance of org.apache.html.dom.HTMLDocumentImpl. See the JavaDocs for that class for further details (LINK: -> JavaDocs; LINK: other recommended HTML parsers)

CHECK with current Online Docs

getProperty(String propname, String defvalue) returns String

Returns any property defined in [AppDir]/app.properties, resp. [HelmaHome]/server.properties that matches the passed property name. This lookup is case-insensitive. Through the optional second parameter it is possible to define a default value that is being returned, in case that that property has not been set.

getURL(String url, Object option) returns MimePart

Retrieves a file/document from the passed URL as a MimePart Obejct, and therefore functions as a minimalist version of a HttpClient. The optional second parameter can either contain a (last-modified) date object, or an eTag string, which will be passed along with the Http request to the specified URL.

Also see the reference on the MimePart Object.

getXmlDocument(Object src) returns Object

Tries to parse an object to a XML DOM tree using the Crimson' Parser. The argument must be either a URL, a piece of XML, an InputStream or a Reader. Returns an instance of org.apache.crimson.tree.XmlDocument. See the JavaDocs for that class for further details (LINK: -> JavaDocs; LINK: other recommended XML parsers)

CHECK with current Online Docs

renderSkin(SkinObject skin, Object param)

Renders the passed SkinObject to the response buffer.

The properties of the optional parameter object are accessible within the skin through the 'param' macro handler.

renderSkin(String skinname, Object param)

Renders a global skin matching the passed name to the response buffer.

The properties of the optional parameter object are accessible within the skin through the 'param' macro handler.

renderSkinAsString(SkinObject skin, Object param) returns String

Returns the result of the rendered SkinObject.

The properties of the optional parameter object are accessible within the skin through the 'param' macro handler.

renderSkinAsString(String skinname, Object param) returns String

Returns the result of a rendered global skin matching the passed name to the response buffer.

The properties of the optional parameter object are accessible within the skin through the 'param' macro handler.

seal(Object obj)

Seals an object, and prevents any further modifications of that object. If any property is tried to be modified after it has been sealed, an error is thrown.

stripTags(String str) returns String

Removes any markup tags contained in the passed string, and returns the modified string.

write(String str)

Writes a string to java.lang.System.out, i.e. to the console. Useful for debugging purposes.

writeln(String str)

Writes a string together with a line break to java.lang.System.out, i.e. to the console. Useful for debugging purposes.

Application Object 'app'

Within the scripting environment Helma provides a host object representing the application itself. This object is always present, and does not need to be instantiated.

For further details also see the JavaDocs for helma.framework.core. ApplicationBean. Since that class is a JavaBean all get- and set-methods are also directly available as properties of that object.

helma.framework.core.Application app.__app__

This property contains a reference to Helma's application class, representing the currently running application, and offers some additional public methods. See Helma's JavaDocs on helma.framework.core.Application for more information.

app.getActiveThreads() returns Int

Returns the number of currently active threads (=request evaluators).

app.getActiveUsers() returns User[]

Returns an array of Users, that are currently logged in.

app.addCronJob(String functionName)

Adds a global function to the list of CronJobs, that are being called periodically. If the property 'schedulerInterval' has not been set otherwise in app.properties, the function will be called every 60 seconds.

app.addCronJob(String functionName, String year, String month, String day, String weekday, String hour, String minute)

Adds a global function to the list of CronJobs, that are being called periodically. By passing along further arguments it is possible to define at what times that function should be called. The same syntax ('*', '1,10,15', '1-5',..) as for Unix' crontab file can be used. Note, that if the property 'schedulerInterval' has been set in app.properties below 60, the function will be called several times in the minute, that it is supposed to run.

app.getAppDir() returns String

Returns the absolute path to the application directory. For multiple repositories this is either, the directory specified as 'appdir' in apps.properties, or the first FileRepository occurring in the repository list.

app.getCacheUsage() returns Int

Returns the number of currently cached objects for the current application.

app.getCronJobs() returns Object

Returns a JavaScript object with the function name as property names and the helma.util.CronJob instance as property values.

app.clearCache()

Removes all objects from the object cache for the current application. By calling this method it is possible to force Helma to fetch all objects fresh from the database.

app.countSessions() returns Int

Returns the number of currently active sessions.

app.createSession(String sessionID) returns SessionObject

Creates a SessionObject with the passed sessionID as its unique identifier. If such a session with that ID already exists, it will return that session.

Object app.data

This property offers the possibility to store arbitrary data on an application wide level, and is available as long as the application is running. Note, that this can just be used as a temporary storage (i.e. as a 'cache'), since this data is not stored persistently within Helma, and is lost when the application is restarted.

app.debug(String str)

Writes a string to the eventLog-file, if debug is set to true in app.properties.

app.debug(String logname, String str)

Writes a string to a logfile named 'logname', if debug is set to true in app.properties.

app.getDir() returns String

Returns the absolute path to the application directory. For multiple repositories this is either, the directory specified as 'appdir' in apps.properties, or the first FileRepository occurring in the repository list.

app.getErrorCount() returns Int

Returns the number of errors that have occurred since the application has been started.

app.getFreeThreads() returns Int

Returns the number of currently free threads (i.e. request evaluators). This is equivalent to app.getMaxThreads() minus app.getActiveThreads().

app.getSession(String sessionID) returns SessionObject

Returns a SessionObject identified through the passed sessionID, if such a session exists.

app.getSessions() returns SessionObject[]

Returns an array of all currently active sessions, represented as SessionObjects.

app.getSessionsForUser(String username) returns SessionObject[]

DEPRECATED

Returns an array of all currently active sessions, which have been associated with a certain user, that is identified through the passed username. Returns an empty array if no such User can be found.

app.getSessionsForUser(User usr) returns SessionObject[]

Returns an array of all currently active sessions, which have been associated with the passed User. Returns an empty array if no User is passed.

app.getSkinfiles() returns Map

Returns a Map that allows access to all defined file-based skins. The map contains for each prototype one entry (for prototypes containing also uppercase letters, also an entry with the lowercased prototype name is contained). This entry contains for each skin file residing in that prototype directory, an entry with the name of the file and the content/source of that file as its value.

app.getUser(String username) returns User

DEPRECATED

Returns a User identified through the passed username. The prototype User must have a username defined through the '_name'-property in type.properties for this to work.

app.log(String str)

Writes a string to the eventLog-file.

app.log(String logname, String str)

Writes a string to a logfile named 'logname'.

Int app.maxThreads

This property contains the maximum number of threads (=request evaluators) that are being created by Helma to handle incoming requests. This property is read- and write-able.

Map app.modules

This property offers a dedicated place to store module-related data on an application wide level. Note, that this can just be used as a temporary storage (i.e. as a 'cache'), since this data is not stored persistently within Helma, and is lost when the application is restarted.

app.getName() returns String

Returns the name of the current application, i.e. the name used in apps.properties.

Map app.properties

This property offers access to each defined key/value pair defined in either app.properties or in server.properties. This property is read-only.

app.getRegisteredUsers() returns User[]

DEPRECATED

Returns an array of all created Users.

app.registerUser(String username, String password)

DEPRECATED

Creates a new HopObject of prototype User, stores it persistently, and associates the current session with that User. The prototype User must have a username defined through the '_name'-property in type.properties, and must have a property named 'password'.

app.removeCronJob(String functionName)

Removes a CronJob, identified through the passed function name, from the list of CronJobs.

app.getRequestCount() returns Int

Returns the number of web requests that occurred since the application has been started.

app.getServerDir() returns String

Returns the absolute path to the home directory of this Helma installation. If Helma is run in embedded mode, this will be equal to the application directory.

app.getUpSince() returns Date

Returns the timestamp of when that application has been started.

app.getXmlrpcCount() returns Int

Returns the number of XmlRpc requests that occurred since the application has been started.

Hop Object

A HopObject is an extended JavaScript object, providing the concept of so called collections, i.e. containers of other HopObjects. Each instantiated prototype in Helma is a scripted HopObject, with additional HopObjects for each of its defined collections and mountpoints.

HopObjects can be in transient state or are persistently mapped on a database. For further details see the according section in the User's Guide.

http://helma.org/docs/reference/hopobject/

see JavaDocs for helma.scripting.rhino.HopObject

HopObject.getById(Int id, String prototypename) return HopObject

Fetches a HopObject of a certain prototype through its ID and its prototype name. The prototype name can either be passed as a second argument, or as an alternative, the function can also be called on the prototype itself with a single argument (e.g. Story.getById(123)).

In case of multiple prototypes being mapped on the same table (which is for instance the case with inherited prototypes) Helma will not check whether the prototype of the fetched object actually matches the specified prototype.

Note, that this refers to the static method 'getById', not to be mixed up with the method getById called on a specific HopObject.

obj.add(HopObject child) returns Boolean

Adds a HopObject to a collection. If the HopObject, on which that function is called on, is persistent, then the added HopObject will also be made persistent. Returns true in case of success.

obj.addAt(Int index, HopObject child) returns Boolean

Adds a HopObject to a collection at a certain position, and shifts the index of all succeeding objects in that collection by one. Index positions start with 0. Just makes sense for HopObjects, that are not mapped on a relational DB, since the sort order of the collection would in such a case be defined by type.properties, resp. by the database itself. Returns true in case of success.

HopObject obj.cache

This property contains a transient HopObject, which can be used for caching purposes. Information stored in that property will get lost as soon as the application is restarted, or that particular HopObject gets kicked out of Helma's ObjectCache, or if the method clearCache is being called.

obj.clearCache()

Removes all information stored in the property obj.cache. Just calling 'obj.cache = null' is not possible, since the property itself can not be set.

obj.contains(HopObject obj) returns Int

Returns the position index of the passed HopObject in that collection (with 0 being the first element in the collection). If the passed HopObject is not contained in that collection -1 will be returned.

obj.count() returns Int

Returns the size of that collection. This method is equivalent to obj.size().

obj.get(Int index) returns HopObject

Fetches a HopObject from a collection through its index position. If the passed index is too large, then 'null' will be returned. If the passed index is negative, a java.lang.ArrayIndexOutOfBoundsException will be thrown.

obj.get(String str) returns HopObject

Fetches a HopObject from a collection through its accessname, which needs to be specified for that collection in the according type.properties, and which needs to be a unique identifier in that collection.

This method just works for persistent HopObjects. If no specific accessname is defined in type.properties, the id will be taken as accessname.

obj.getById(String str) returns HopObject

FIXME

obj.href(String action) returns String

FIXME

obj.invalidate() returns Boolean

FIXME

obj.invalidate(String childId) returns Boolean

FIXME

obj.list() returns HopObject[]

Returns the contained HopObjects in that collection as an array, with the sort order being preserved. Note, that this function should not be called on very large collections, since on the one hand Helma needs to fetch all contained HopObjects, and on the other hand JavaScript is not well optimized for handling large arrays.

obj.list(Int start, Int length) returns HopObject[]

Returns all contained HopObjects, starting from a certain index position until another certain index position, as an array. Both arguments need to be specified.

obj.persist() returns Int

FIXME

obj.prefetchChildren(Int startIndex, Int length)

FIXME

obj.remove() returns Boolean

FIXME

obj.removeChild(HopObject child) returns Boolean

FIXME

obj.renderSkin(SkinObject skin, Object param) returns Boolean

FIXME

obj.renderSkin(String skinname, Object param) returns Boolean

FIXME

obj.renderSkinAsString(SkinObject skin, Object param) returns String

FIXME

obj.renderSkinAsString(String skinname, Object param) returns String

FIXME

obj.set(String key, Object value) returns Boolean

FIXME

obj.size() returns Int

Returns the size of that collection. This method is equivalent to obj.size().

MimePart

see JavaDocs for helma.util.MimePart

new Packages.helma.util.MimePart(String name, byte[] content, String contentType)

FIXME

part.contentLength returns Int

FIXME

part.contentType returns String

FIXME

part.eTag returns String

FIXME

part.getContent() returns byte[]

FIXME

part.getText() returns String

FIXME

part.lastModified returns Date

FIXME

part.name returns String

FIXME

part.writeToFile(String dir) returns String

FIXME

part.writeToFile(String dir, String fname) returns String

FIXME

onXYZ() Event Functions

onCodeUpdate()

FIXME

onLogout()

FIXME

onRequest()

FIXME

onStart()

FIXME

Request Object 'req'

http://helma.org/docs/reference/request/

see JavaDocs for helma.framework.RequestBean

String req.action

Returns the name of the requested action (without the suffix '_action). This property is read-only.

Object req.data

Returns an object containing all passed request parameters as named properties, no matter whether these have been submitted as URL-parameters, as part of a HTTP POST request, or as cookie values.

If more than one value is submitted for one parameter name, the values are stored inside an array called req.data.paramname_array, that is the _array suffix is added to the parameter name. req.data.paramname itself will just contain a single value.

Uploaded files are available in req.data as a MimePart object.

Additionally Helma sets the following HTTP environment variables if they are available:

authorization

Equivalent to the variable 'authorization' sent in the request header.

http_browser

Name and version of the client browser. Equivalent to the variable 'User-Agent' sent in the request header.

http_host

Host name to which that request was sent to. Equivalent to the variable 'Host' sent in the request header.

http_language

Equivalent to the variable 'Accept-Language' sent in the request header.

http_language

Equivalent to the variable 'Accept-Language' sent in the request header.

http_remotehost

IP-Address of the client machine. Equivalent to a getRemoteAddr() call on the servletRequest.

http_referer

URL of the page the user came from. Equivalent to the variable 'Referer' sent in the request header.

All properties of req.data are read- and write-able.

req.isGet() returns Boolean

Returns true if the current request is a HTTP GET request, false otherwise.

req.isPost() returns Boolean

Returns true if the current request is a HTTP POST request, false otherwise.

req.getMethod() returns String

Returns the HTTP method (in uppercase letters) of the current request, which is usually 'GET' or 'POST'. For non-web-requests this function will return on of the following: 'XMLRPC', 'EXTERNAL' or 'INTERNAL'.

req.getPassword() returns String

Returns the according decrypted password, if the request contains user credentials sent with 'basic authentication scheme' method, typically as a result of a previously returned 401 HTTP response. (LINK: http://en.wikipedia.org/wiki/Basic_authentication_scheme)

String req.path

Returns the path of the current request, relative to the mountpoint of the current application, and without a preceding slash. This property is read-only.

req.getRuntime() returns Int

Returns the amount of time that has elapsed since the start of the processing of the current request, measured in milliseconds.

req.getServletRequest() returns javax.servlet.http.HttpServletRequest

Returns an instance of the Java HttpServletRequest Class corresponding to the current request, which allows full access to the methods of that class.

req.username

Returns the according decrypted username, if the request contains user credentials sent with 'basic authentication scheme' method, typically as a result of a previously returned 401 HTTP response. (LINK: http://en.wikipedia.org/wiki/Basic_authentication_scheme)

Response Object 'res'

http://helma.org/docs/reference/response/

see JavaDocs for helma.framework.ResponseBean

res.abort()

FIXME

res.cache returns Boolean

FIXME

res.charset

FIXME

res.commit()

FIXME

res.contentType returns String

FIXME

res.data

FIXME

res.debug(String)

FIXME

res.dependsOn(String)

FIXME

res.digest()

FIXME

res.encode(String)

FIXME

res.encodeXml(String)

FIXME

res.error

FIXME

res.etag

FIXME

res.format(String)

FIXME

res.forward(String url)

FIXME

res.handlers

FIXME

res.lastModified returns Date

FIXME

res.message

FIXME

res.meta

FIXME

res.pop() returns String

FIXME

res.push()

FIXME

res.realm

FIXME

res.redirect(String)

FIXME

res.reset()

FIXME

res.servletResponse returns javax.servlet.http.HttpServletResponse

FIXME

res.setCookie(String key, String value, Int days, String path, String domain)

FIXME

res.skinpath

FIXME

res.status

FIXME

res.write(String str)

FIXME

res.writeBinary(ByteArray bytes)

FIXME

res.writeln(String str)

FIXME

SessionObejct 'session'

Each web request is associated with a SessionObject representing a 'user session'. Helma recognises requests being made from the same client within the same session through a session cookie named 'HopSession'. If no such cookie is sent with the request, Helma will set that a cookie with a random hash with the next response.

Within the scripting environment 'session' always represent the current session of the user, who initiated the web request. Furthermore it is also possible to fetch active sessions of other clients through the method app.getSessions(), and to artificially create SessionObjects through app.createSession().

For further details also see the JavaDocs for helma.framework.core.SessionBean. Since that class is a JavaBean all get- and set-methods are also directly available as properties of that object.

String session._id

Contains the unique identifier of the current session, which is equivalent to the value stored in the HopSession-cookie on the client side. This property is read-only.

String session.cookie

Contains the unique identifier of the current session, which is equivalent to the value stored in the HopSession-cookie on the client side. This property is read-only.

HopObject session.data

This property of the SessionObject offers the possibility to store arbitrary data within the current user session. Note, that this can just be used as a temporary storage, since sessions are not stored persistently within Helma, and are generally lost when the application is restarted.

Date session.lastActive

Contains the timestamp of the last web request, that has been submitted by that client. This property is read-only, but can be set to the current time through session.touch().

Date session.lastModified

Contains the timestamp of when the associated client started the session, or logged in, or logged out the last time, whichever happened most recently. This property is read- and write-able.

String session.message

??? -> HANNES

Date session.onSince

Contains the timestamp of when the client started the session. This property is read-only.

User session.user

Contains a reference to the UserObject associated with this session. This property is null if the client has not been logged in yet, or has already been logged out. Checking this for being unequal to null is the usual way to check whether a client is logged in or not. This property is read-only, but can be set through the method session.login(User usr).

session.lastActive() returns Date

Returns the timestamp of the last web request, that has been submitted by that client.

session.login(User usr)

Associates the passed User to that session, i.e. logs the client in as that User. The property user of the session object will refer to the User.

session.login(String username, String password) returns Boolean

DEPRECATED

Fetches a User via the passed username (which is defined through _name in User/type.properties, and which needs to be unique), checks whether the passed password matches the password of that User (the password property actually needs to be named 'password' in User/type.properties), and in case of a match, actually associates that session with that User. The property user of the session object will then refer to the User.

If either such a User is not found, or the password does not match the method will return false.

session.logout()

Logs out the current session, i.e. removes the reference to a User if one exists. Additionally the global function onLogout will be called.

session.onSince() returns Date

Returns the timestamp of when the client started the session.

session.touch()

This will set the lastActive property to the current timestamp, and can be used to artificially avoid a session timeout.

Skin Object

http://helma.org/docs/reference/skin/

see JavaDocs for helma.framework.core.Skin

sk.allowMacro(String macroname)

FIXME

sk.containsMacro(String macroname) returns Boolean

FIXME

sk.getSource() returns String

FIXME