## global

    Object
       |
       +--global

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Properties Summary
`app` | `app` This object is automatically instantiated as the app property of the global object (or global.app) and there is no constructor to instantiate further instances.
`File` | `File` Constructor for File objects, providing read and write access to the file system.
`FtpClient` | `FtpClient` Constructor for File objects, to send and receive files from an FTP server.
`HopObject` | `HopObject` Constructor for HopObject objects, providing the building blocks of the Helma framework.
`Image` | `Image` Helma's built-in image object allows you to read, manipulate, and save images.
`Mail` | `Mail` Helma's built-in mail client enables you to send e-mail via SMTP.
`PathWrapper` | `path` Accessing objects in the URI path.
`XmlRpcObject` | `Remote` Constructor for Remote objects, implementing an XML-RPC client.
`req` | `req` This object is automatically instantiated as the req property of the global object (or global.req) and there is no constructor to instantiate further instances.
`res` | `res` This object is automatically instantiated as the res property of the global object (or global.res) and there is no constructor to instantiate further instances.
`HopObject` | `root` Represents the root of the object model hierarchy.
`session` | `session` This object is automatically instantiated as the session property of the global object (or global.session).
`HopObject` | `User` The built-in User prototype.
`Xml` | `Xml` The Xml object provides easy means to convert XML to HopObject and HopObjects to XML.
`<static> Object` | `helma` Library object for the HelmaLib javascript library.

Methods Summary
`Boolean` | `authenticate(<String> username,<String> password)` Authenticates a user against a standard Unix password file.
`Skin` | `createSkin(<String> skin)` Creates a Skin object from the passed String.
`void` | `defineLibraryScope(<String> namespace)` Declares a custom global namespace that will not be garbage collected.
`Object` | `deserialize(<String> filename)` Deserialize a JavaScript object that was previously serialized to a file.
`String` | `encode(<String> text)` Encodes a string for HTML output and inserts linebreak tags.
`String` | `encodeForm(<String> text)` Encodes a string for HTML output, leaving linebreaks untouched.
`String` | `encodeXml(<String> text)` Encodes a string for XML output.
`String` | `format(<String> text)` Encodes a string for HTML output, leaving existing markup tags untouched.
`String` | `formatParagraphs(<String> text)` Encodes a string for HTML output, inserting paragraph tags.
`DatabaseObject` | `getDBConnection(<String> datasource)` Connects to a relational database, and returns a DatabaseObject representing that connection.
`HTMLDocumentImpl` | `getHtmlDocument(<String> source)` Parses an HTML string to an XML DOM tree.
`String` | `getProperty(<String> property,<String> defaultvalue)` Looks up a property that was set in app.properties or server.properties Returns any property defined in [AppDir]/app.properties, resp.
`MimePart` | `getURL(<String> url,<String> etagOrDate)` Retrieves a file/document from the passed URL as a MimePart Object, and therefore functions as a minimalist version of a HttpClient.
`XmlDocument` | `getXmlDocument(<String> source)` Parses an XML string to an XML DOM tree.
`void` | `onCodeUpdate()` If defined, the onCodeUpdate() function is called whenever the code is recompiled.
`void` | `onLogout()` If defined, the onLogout() function is called when a user is logged out.
`void` | `onRequest()` If defined, the onRequest() function is called before each page request is handled.
`void` | `onResponse()` If defined, the onResponse() function is called after each page request is handled but before the response is returned.
`void` | `onStart()` If defined, the onStart() function is called when the application is started.
`void` | `onStop()` If defined, the onStop() function is called when the application is stopped.
`void` | `renderSkin(<String> skin,<Object> params)` Renders the passed SkinObject or a global skin matching the passed name to the response buffer.
`String` | `renderSkinAsString(<String> skin,<Object> params)` Returns the result of the rendered SkinObject or a rendered global skin matching the passed name.
`void` | `seal(<Object> obj)` Seals an object, and prevents any further modifications of that object.
`void` | `serialize(<Object> obj,<String> filename)` Serialize a JavaScript object to a file.
`String` | `stripTags(<String> markup)` Removes any markup tags contained in the passed string, and returns the modified string.
`Object` | `toJava(<Object> obj)` Converts a Javascript String, Date, etc to its Java counterpart.
`Map` | `unwrapJavaMap(<Object> obj)` Unwrap a map previously wrapped using wrapJavaMap().
`Object` | `wrapJavaMap(<Packages.java.util.Map> obj)` Wrap a java.util.Map so that it looks and behaves like a native JS object.
`void` | `write(<String> text)` Writes a string to java.lang.System.out, i.e.
`void` | `writeln(<String> text)` Writes a string together with a line break to java.lang.System.out, i.e.
`<static> void` | `now_macro(param)` renders the current datetime
`<static> void` | `property_macro(param)` write out a property contained in app.properties
`<static> void` | `skin_macro(param)` renders a global skin
`<static> void` | `write_macro(param)` wrapper to output a string from within a skin just to be able to use different encodings

Properties Detail

### app

    app app

This object is automatically instantiated as the app property of the global object (or global.app) and there is no constructor to instantiate further instances.
The app object is a host object representing the application for which the current scripting environment is provided.
For further details also see the JavaDocs for Packages.helma.framework.core.ApplicationBean. Since that class is a JavaBean all of its get- and set-methods are also directly available as properties of this object.

### File

    File File

Constructor for File objects, providing read and write access to the file system.
Example:

     var fileOrDir = new File('static/test.txt');

### FtpClient

    FtpClient FtpClient

Constructor for File objects, to send and receive files from an FTP server.
The FTP client needs Daniel Savarese's NetComponents library in the classpath in order to work.
Example:

     var ftp = new FtpClient("ftp.mydomain.com");

### HopObject

    HopObject HopObject

Constructor for HopObject objects, providing the building blocks of the Helma framework.
Extends the standard JavaScript object with Helma-specific properties and functions. The HopObject is the basic building block of a Helma application. The website root object as well as custom types defined by the application inherit from the HopObject prototype.
HopObjects can be given special Helma specific properties, such as "collections" that can be configured to map to relational databases, and will make such data available when rendering "skins".
HopObjects can be in transient state or are persistently mapped on a database. HopObjects that are directly or indirectly attached to the application's root object are automatically persisted using the built-in XML database, if they are not otherwise mapped to a relational database. see JavaDocs for helma.scripting.rhino.HopObject

### Image

    Image Image

Helma's built-in image object allows you to read, manipulate, and save images.
An image object is created using the Image() constructor.
Example:

     var img = new Image("http://helma.org/image.gif");

### Mail

    Mail Mail

Helma's built-in mail client enables you to send e-mail via SMTP.
A mail client object is created by using the Mail() constructor. The mail object then can be manipulated and sent using the methods listed below.
You'll need the JavaMail library installed for this to work. Also, don't forget to set your mail server via the smtp property in the app.properties or server.properties file.
Note: Make sure that the SMTP server itself is well-configured, so that it accepts e-mails coming from your server and does not deny relaying. Best and fastest configuration is of course if you run your own SMTP server (e.g. postfix) which might be a bit tricky to set up, however.

### path

    PathWrapper path

Accessing objects in the URI path.
The objects in the URI request path are accessible as array members of the global path object as well as named properties of path via their prototype name.
When Helma receives an HTTP request e.g. from a browser, it maps the URI path of the URL to HopObjects. This way, the path is interpreted as an hierarchy of HopObjects.
For instance, if an object in the URI path has a prototype called "story", it will be accessible as path["story"] or path.story.

     for (var i=0; i < path.length; i++)
       res.writeln(path[i]);

     HopObject file
     HopObject document
     HopObject story
     HopObject note

     var obj = path.story;
     res.write(obj);

     HopObject story

The path object behaves similar to a Javascript array, but it is actually an instance of the Packages.helma.scripting.rhino.PathWrapper Java class.

### Remote

    XmlRpcObject Remote

Constructor for Remote objects, implementing an XML-RPC client.
XML-RPC is a simple framework to enable one machine to execute remote procedures on another using HTTP and XML.
In Helma such calls are performed using a Remote object. Remote objects are created with the URL of the XML-RPC service. Functions of the remote XML-RPC service then can be called just like local functions.
To compensate for the missing exception handling, Remote objects return result wrappers which contain either the result of the remote function, or a description of the error if one occurred.
Example:

     var xr = new Remote("http://helma.domain.tld:5056/");
     var msg1 = xr.helmaorg.getXmlRpcMessage();
     if (msg1.error)
       res.write(msg1.error);
     else
       res.write(msg1.result);

     Hello, Xml-Rpc World!

     var msg2 = xr.hotelGuide.hotels.grandimperial.getXmlRpcMessage();
     if (!msg2.error)
       res.write(msg2.result);

     Welcome to the Grand Imperial Hotel, Vienna!

     var msg3 = xr.kolin.document.comments["23"].getXmlRpcMessage();
     if (!msg3.error)
       res.write(msg3.result);

     Here you can write your comments.

     var xr = new Remote("http://betty.userland.com/RPC2");
     var state = xr.examples.getStateName(23);
     if (!state.error)
       res.write(state.result);

     Minnesota

### req

    req req

This object is automatically instantiated as the req property of the global object (or global.req) and there is no constructor to instantiate further instances.
The req object is a host object representing the request that is currently handled by the scripting environment.

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

### res

    res res

This object is automatically instantiated as the res property of the global object (or global.res) and there is no constructor to instantiate further instances.
The res object is a host object representing the response for the request that is currently handled by the scripting environment.
For further details also see the JavaDocs for Packages.helma.framework.ResponseBean. Since that class is a JavaBean all of its get- and set-methods are also directly available as properties of this object.

### root

    HopObject root

Represents the root of the object model hierarchy.
Each application has only one root object. This single instance of the root object inherits its properties from the Root prototype, which itself inherits from the HopObject prototype.
The root object serves as the starting point against which the URI path of incoming requests are resolved.

### session

    session session

This object is automatically instantiated as the session property of the global object (or global.session).
The session object is a host object representing the session for the request that is currently handled by the scripting environment.
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 represents the current session of the user, who initiated the web request.
Besides that default session object, it is also possible to fetch active sessions of other clients through the method app.getSessions(), and to create additional SessionObjects through app.createSession().
For further details also see the JavaDocs for Packages.helma.framework.core.SessionBean. Since that class is a JavaBean all get- and set-methods are also directly available as properties of that object.

### User

    HopObject User

The built-in User prototype.
See:

- session.user
- session.login
- session.logout

### Xml

    Xml Xml

The Xml object provides easy means to convert XML to HopObject and HopObjects to XML.

### helma

    <static> Object helma

Library object for the HelmaLib javascript library.
HelmaLib is organized into two groups of modules:

- modules/core which contains extensions to core JavaScript types such as Object, Array, or Date.
- modules/helma which provides new functionality to JavaScript, usually by wrapping a Java library.

To use a HelmaLib module in your Helma application, you need to add it to the app's repositories. The simplest way to do so is by using the app.addRepository() function:

    app.addRepository("modules/helma/Search.js");

See:

- Array
- Date
- Number
- Object
- String
- helma.Aspects
- helma.Chart
- helma.Color
- helma.Database
- helma.File
- helma.Ftp
- helma.Html
- helma.Http
- helma.Mail
- helma.Search
- helma.Skin
- helma.Ssh
- helma.Url
- helma.Zip

If you are looking for more Helma libraries, be sure to check out the Jala project!

Method Detail

### authenticate

    Boolean authenticate(<String> username,<String> password)

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.
Example:

     var login = authenticate("user", "pass");
     if (login)
        res.write("Welcome back!");
     else
        res.write("Oops, please try again...");

     Welcome back!

Parameters:

`username` - as String

`password` - as String

Returns:

Boolean true or false depending on whether the authentication was successful

### createSkin

    Skin createSkin(<String> skin)

Creates a Skin object from the passed String.
The returned object can be passed to the global functions renderSkin(), resp. renderSkinAsString().
Skins can also be defined by text files using a *.skin suffix, placed in an application's code repository. The createSkin method provides the ability to create skins dynamically as an alternative.
Example:

     var str = "Hello, <% response.body %>!";
     var skin = createSkin(str);
     res.data.body = "World";
     renderSkin(skin);

     Hello, World!

Parameters:

`skin` - as String

Returns:

Skin generated from the skin string

See:

- Skin
- renderSkin()
- renderSkinAsString()

### defineLibraryScope

    void defineLibraryScope(<String> namespace)

Declares a custom global namespace that will not be garbage collected.

Parameters:

`namespace` - as String, the name of the protected namespace

### deserialize

    Object deserialize(<String> filename)

Deserialize a JavaScript object that was previously serialized to a file.

Parameters:

`filename` - as String, the file to deserialize the object from

Returns:

Object the deserialized object

### encode

    String encode(<String> text)

Encodes a string for HTML output and inserts linebreak tags.
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.

Example:

     var str = encode("<b>Bananer växer\n minsann inte på träd.<b>");
     res.write(str);

     &lt;b&gt;Bananer v&auml;xer
     <br /> &lt;br&gt; minsann inte p&aring; tr&auml;d.&lt;/b&gt;

Parameters:

`text` - as String

Returns:

String the modified string

See:

- encodeForm()
- encodeXml()
- format()
- formatParagraphs()

### encodeForm

    String encodeForm(<String> text)

Encodes a string for HTML output, leaving linebreaks untouched.
Performs the following string manipulations:

- Unlike encode(), leaves linebreaks untouched. This is what you usually want to do for encoding form content (esp. with text input values).
- All special characters (i.e. non ASCII) are being replaced with their equivalent HTML entity.
- Existing markup tags are being encoded.

Example:

     var str = encodeForm("<b>Bananer växer\n minsann inte på träd.</b>");
     res.write(str);

     &lt;b&gt;Bananer v&auml;xer
     minsann inte p&aring; tr&auml;d.&lt;/b&gt;

Parameters:

`text` - as String

Returns:

String the modified string

See:

- encode()
- encodeXml()
- format()
- formatParagraphs()

### encodeXml

    String encodeXml(<String> text)

Encodes a string for XML output.
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

Example:

     var str = encodeXml("<title>Smørebrød</title>");
     res.write(str);

     &lt;title&gt;Smørebr&amp;oslash:d&lt;/title&gt;

Parameters:

`text` - as String

Returns:

String the modified string

See:

- encode()
- encodeForm()
- format()
- formatParagraphs()

### format

    String format(<String> text)

Encodes a string for HTML output, leaving existing markup tags untouched.
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.

Example:

     var str = format("<b>Bananer växer\n minsann inte på träd.</b>");
     res.write(str);

     <b>Bananer v&auml;xer
     <br /> minsann inte p&aring; tr&auml;d.</b>

Parameters:

`text` - as String

Returns:

String the modified string

See:

- encode()
- encodeForm()
- encodeXml()
- formatParagraphs()

### formatParagraphs

    String formatParagraphs(<String> text)

Encodes a string for HTML output, inserting paragraph tags.
Performs the following string manipulations:

- Empty lines (double line breaks) are considered to indicate a paragraph, and are surrounded with <p> tags.
- All single 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.

Example:

     var str = format("Smørebrød:\n\n<b>Bananer växer\n minsann inte på träd.</b>");
     res.write(str);

     <p>Sm&oslash;rebr&oslash;d:</p>

     <p><b>Bananer v&auml;xer
     <br /> minsann inte p&aring; tr&auml;d.</b></p>

Parameters:

`text` - as String

Returns:

String the modified string

See:

- encode()
- encodeForm()
- encodeXml()
- format()

### getDBConnection

    DatabaseObject getDBConnection(<String> datasource)

Connects to a relational database, and returns a DatabaseObject representing that connection.
The Direct DB interface allows the developer to directly access relational databases defined in the db.properties file without going through the Helma object model layer.
The passed string must match one of the data sources being defined in [AppDir]/db.properties, or an error will be thrown. Also see the reference on the DatabaseObject and the documentation for the methods of the returned dbConnection and dbIterator objects.
Example:

     var dbConnection = getDBConnection("db_source_name");

     var dbRowset = dbConnection.executeRetrieval("select title from dummy");
     while (dbRowset.next())
       res.writeln(dbRowset.getColumnItem("title"));

     var deletedRows = dbConnection.executeCommand("delete from foobar");
     if(deletedRows){
       res.writeln(deletedRows + " rows successfully deleted");
     }

See the documentation of the databaseObject for a list of the available methods and properties of the returned object.

Parameters:

`datasource` - name as String

Returns:

Packages.helma.scripting.rhino.extensions.DatabaseObject - a reference to the created db connection

See:

- Packages.helma.scripting.rhino.extensions.DatabaseObject
- DatabaseObject
- DatabaseObject.RowSet

Deprecated use helma.Database instead

### getHtmlDocument

    HTMLDocumentImpl getHtmlDocument(<String> source)

Parses an HTML string to an XML DOM tree.
Tries to parse a string 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.

FIXME: Links to other recommended HTML parsers

Parameters:

`source` - as String, HTML formatted

Returns:

Packages.org.apache.html.dom.HTMLDocumentImpl XML DOM tree object

See:

- Packages.org.apache.html.dom.HTMLDocumentImpl
- getXmlDocument()

### getProperty

    String getProperty(<String> property,<String> defaultvalue)

Looks up a property that was set in app.properties or server.properties 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 the property has not been set.

Parameters:

`property` - as String, the name of the property to look up

`defaultvalue` - as String, optional default/fallback value

Returns:

String with the resulting value for the checked property

### getURL

    MimePart getURL(<String> url,<String> etagOrDate)

Retrieves a file/document from the passed URL as a MimePart Object, 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

Parameters:

`url` - as String

`etagOrDate` - either the etag as String or a Date object

Returns:

Packages.helma.util.MimePart MimePart object of received Http response

See:

- Packages.helma.util.MimePart
- mimePart

### getXmlDocument

    XmlDocument getXmlDocument(<String> source)

Parses an XML string to an XML DOM tree.
Tries to parse a string 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.

FIXME: Link to JavaDocs and other recommended XML parsers

Parameters:

`source` - as String, using XML syntax

Returns:

Packages.org.apache.crimson.tree.XmlDocument XML DOM tree object

See:

- getHtmlDocument()

### onCodeUpdate

    void onCodeUpdate()

If defined, the onCodeUpdate() function is called whenever the code is recompiled. This is most useful when code from repositories is dynamically modified by the application during runtime.

### onLogout

    void onLogout()

If defined, the onLogout() function is called when a user is logged out.

### onRequest

    void onRequest()

If defined, the onRequest() function is called before each page request is handled.

### onResponse

    void onResponse()

If defined, the onResponse() function is called after each page request is handled but before the response is returned.
This method is NOT called when a response is forwarded or redirected using res.forward or res.redirect respectively.
You can access the current repsonse buffer using the method res.getBuffer.

See:

- res.getBuffer

### onStart

    void onStart()

If defined, the onStart() function is called when the application is started.
This is most useful for any initialization purposes your application may require.

### onStop

    void onStop()

If defined, the onStop() function is called when the application is stopped.

### renderSkin

    void renderSkin(<String> skin,<Object> params)

Renders the passed SkinObject or 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.

Parameters:

`skin` - as SkinObject or the name of the skin as String

`params` - as Object, optional properties to be passed to the skin

### renderSkinAsString

    String renderSkinAsString(<String> skin,<Object> params)

Returns the result of the rendered SkinObject or a rendered global skin matching the passed name. The properties of the optional parameter object are accessible within the skin through the 'param' macro handler.

Parameters:

`skin` - as SkinObject or the name of the skin as String

`params` - as Object, optional properties to be passed to the skin

Returns:

String of the rendered skin

### seal

    void 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.

Parameters:

`obj` - that is to be sealed

### serialize

    void serialize(<Object> obj,<String> filename)

Serialize a JavaScript object to a file.

Parameters:

`obj` - as Object, the object to be serialized

`filename` - as String, the file to serialize the object to

### stripTags

    String stripTags(<String> markup)

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

Parameters:

`markup` - as String, the text that is to be stripped of tags

Returns:

String with the tags stripped out

### toJava

    Object toJava(<Object> obj)

Converts a Javascript String, Date, etc to its Java counterpart.
Converts an object into a wrapper that exposes the java methods of the object to JavaScript. This is useful for treating native numbers, strings, etc as their java counterpart such as java.lang.Double, java.lang.String etc.

Parameters:

`obj` - as String, Date, Boolean, Number, etc.

Returns:

NativeJavaObject wrapping the provided object

### unwrapJavaMap

    Map unwrapJavaMap(<Object> obj)

Unwrap a map previously wrapped using wrapJavaMap().

Parameters:

`obj` - as Object, a map previously wrapped using wrapJavaMap()

Returns:

Packages.java.util.Map the unwrapped map object

See:

- Packages.java.util.Map
- wrapJavaMap()

### wrapJavaMap

    Object wrapJavaMap(<Packages.java.util.Map> obj)

Wrap a java.util.Map so that it looks and behaves like a native JS object.

Parameters:

`obj` - as Packages.java.util.Map to be wrapped

Returns:

Object wrapping the map, making it look like a JS object

See:

- unwrapJavaMap()

### write

    void write(<String> text)

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

Parameters:

`text` - as String, the message that is to be output

### writeln

    void writeln(<String> text)

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

Parameters:

`text` - as String, the message that is to be output

### now_macro

    <static> void now_macro(param)

renders the current datetime

Parameters:

`Object` - containing a formatting string as format property

### property_macro

    <static> void property_macro(param)

write out a property contained in app.properties

Parameters:

`Object` - containing the name of the property

### skin_macro

    <static> void skin_macro(param)

renders a global skin

### write_macro

    <static> void write_macro(param)

wrapper to output a string from within a skin just to be able to use different encodings

Parameters:

`Object` - containing the string as text property

SUMMARY: Constructor | Properties | Methods | DETAIL: Constructor | Properties | Methods

Documentation generated by JSDoc on Thu Apr 5 01:59:00 2007