## app

    Object
       |
       +--app

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

Properties Summary
`Application` | `__app__` This property contains a reference this application's instance of the Packages.helma.framework.core.Application class.
`Object` | `data` Object that serves as a cache for application specific data.
`String[]` | `globalMacroPath` The app.globalMacroPath property allows to define a search path for global macros.
`Number` | `maxThreads` This property contains the maximum number of additional threads (=request evaluators) The maximum number of additional threads that are being created by Helma to handle incoming requests.
`Map` | `modules` Map object that can be used as an application wide data cache This property offers a dedicated place to store module-related data on an application wide level.
`Function` | `processMacroParameter` This allows the application to set a callback function for pre-processing macro parameters formatted as $(...).
`Map` | `properties` Map of any specified application or server properties This property offers access to each key/value pair defined in either app.properties or in server.properties.
`Array` | `repositories` List of the application's code repositories This property offers a dedicated place to store module-related data on an application wide level.

Methods Summary
`void` | `addCronJob(functionNameAsString, year, month, day, weekday, hour, minute)` Adds a global function to the list of CronJobs that are being called periodically.
`void` | `addRepository(<String> repository)` Adds a code repository to the current application
`void` | `clearCache()` Removes all objects from the object cache for the current application.
`Number` | `countSessions()` Returns the number of currently active sessions.
`SessionObject` | `createSession(sessionID)` Creates a SessionObject with the passed sessionID as its unique identifier.
`void` | `debug(<String> filenameOrText,<String> text)` Writes a string to a log file if debug is set to true in app.properties.
`Number` | `getActiveThreads()` Returns the number of currently active threads (=request evaluators).
`Array` | `getActiveUsers()` Returns an array of Users, that are currently logged in.
`String` | `getAppDir()` Returns the absolute path to the application directory.
`Number` | `getCacheUsage()` Returns the number of currently cached objects for the current application.
`Object` | `getCronJobs()` Returns an object of scheduled cron jobs.
`String` | `getDir()` Returns the absolute path to the application directory.
`Number` | `getErrorCount()` Returns the number of errors that have occurred since the application has been started.
`Number` | `getFreeThreads()` Returns the number of currently free threads (i.e.
`Number` | `getMaxThreads()` Returns the maximum number of threads (i.e.
`String` | `getName()` Returns the name of the current application, i.e.
`Array` | `getRegisteredUsers()` Returns an array of all existing users.
`Number` | `getRequestCount()` Returns the number of web requests that occurred since the application has been started.
`String` | `getServerDir()` Returns the absolute path to the home directory of this Helma installation.
`SessionObject` | `getSession(<String> sessionID)` Returns a SessionObject identified through the passed sessionID, if such a session exists.
`Array` | `getSessions()` Returns an array of all currently active sessions, represented as SessionObjects.
`Array` | `getSessionsForUser(<User> user)` Returns an array of active sessions for the specified user Returns an array of all currently active sessions, which have been associated with the passed User.
`Map` | `getSkinfiles()` Returns a Map that allows access to all defined file-based skins.
`Date` | `getUpSince()` Returns the timestamp of when that application has been started.
`User` | `getUser(<String> username)` Returns a User identified through the passed username.
`Number` | `getXmlrpcCount()` Returns the number of XmlRpc requests that occurred since the application has been started.
`Object` | `invoke(<Object> thisObject,<Function> fnc,<Array> args,<Number> timeout)` Trigger a synchronous Helma invocation.
`Object` | `invokeAsync(<Object> thisObject,<Function> fnc,<Array> args,<Number> timeout)` Trigger an asynchronous Helma invocation.
`void` | `log(<String> filenameOrText,<String> text)` Writes a string to a log file.
`User` | `registerUser(<String> username, <String> password)` Creates a new User object Creates a new HopObject of prototype User, stores it persistently, and returns the created User object. When mapping the User prototype to a relational database, the type.properties file must contain mappings for the '_name'-property (the username) and for a property named 'password'.
`void` | `removeCronJob(<String> functionName)` Removes a CronJob, identified through the passed function name, from the list of CronJobs.

Properties Detail

### __app__

    Application __app__

This property contains a reference this application's instance of the Packages.helma.framework.core.Application class.
It represents the currently running application, and offers some additional public methods. See Helma's JavaDocs on Packages.helma.framework.core.Application for more information.

### data

    Object data

Object that serves as a cache for application specific 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. However, unlike global properties, any data stored in this object will not be garbage collected during runtime.
Example:

     app.data.runlevel = 4;
     app.data.language = "en";

     res.write(app.data);
     TransientNode app

     for (var p in app.data)
       res.writeln(p + ": " + app.data[p]);
     runlevel: 4
     language: en

     res.write(app.data.runlevel);
     4

     res.write(app.data["language"]);
     en

### globalMacroPath

    String[] globalMacroPath

The app.globalMacroPath property allows to define a search path for global macros. This is a String array containing a list of global namespaces.

### maxThreads

    Number maxThreads

This property contains the maximum number of additional threads (=request evaluators)
The maximum number of additional threads that are being created by Helma to handle incoming requests. This property is readable and writeable.
See also: getActiveThreads(), getFreeThreads(), getMaxThreads()

### modules

    Map modules

Map object that can be used as an application wide data cache
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.
See also: data

### processMacroParameter

    Function processMacroParameter

This allows the application to set a callback function for pre-processing macro parameters formatted as $(...). The function is expected to take the raw parameter value as argument and return the processed parameter.

### properties

    Map properties

Map of any specified application or server properties
This property offers access to each key/value pair defined in either app.properties or in server.properties. These properties are read-only.
Example:

     # File app.properties:
     debug = true
     color = #ffcc00

     res.write(app.properties);
     {debug=true,color=#ffcc00}

     for (var p in app.properties)
       res.writeln(p + ": " + app.properties[p]);
     debug: true
     color: #ffcc00

     res.write(app.properties.debug);
     true

     res.write(app.properties["color"]);
     #ffcc00

### repositories

    Array repositories

List of the application's code repositories
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.
See also: data

Method Detail

### addCronJob

    void addCronJob(functionNameAsString, year, month, day, weekday, hour, minute)

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

Parameters:

`functionName` - as String, name of function to be scheduled as cron job

`crontab` - syntax of comma delimited arguments for year, month, day, weekday, hour, minute

See:

- getCronJobs()
- removeCronJob()

### addRepository

    void addRepository(<String> repository)

Adds a code repository to the current application

Parameters:

`repository` - as String, the path to the code repository

`repository` - as a Repository object, implementing the Repository interface

See:

- repositories

### clearCache

    void clearCache()

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

See:

- getCacheUsage()

### countSessions

    Number countSessions()

Returns the number of currently active sessions.

Returns:

Number of sessions (integer)

See:

- createSession()
- getSession()
- getSessions()
- getSessionsForUser()

### createSession

    SessionObject createSession(sessionID)

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

Parameters:

`String` - of the ID for this session

Returns:

SessionObject for the specified

See:

- countSessions()
- getSession()
- getSessions()
- getSessionsForUser()

### debug

    void debug(<String> filenameOrText,<String> text)

Writes a string to a log file if debug is set to true in app.properties.
Either the text provided as the first argument is written to the eventLog file or the text that is provided as the second argument is written to a log file who's name is specified as the first argument.
Writing to a file can be overridden by setting the property "logdir" in the server.properties or app.properties file to the value "console".
Example:

     # File helma/apps/test/app.properties:
     debug = true

     // File helma/apps/test/root/main.hac:
     app.debug("This message is written to the test application's event log.");
     app.debug("custom", "This message is written to the custom.log file.");

     File helma/log/test_event.log:
     [2006/07/11 17:08] This message is written to the test application's event log.

     File helma/log/custom.log:
     [2006/07/11 17:08] This message is written to the custom.log file.

Parameters:

`filenameOrText` - as String, the log filename to write to or the text to write to the eventLog file

`text` - as String the text to write, if the filename was specified as the first argument

See:

- log()

### getActiveThreads

    Number getActiveThreads()

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

Returns:

Number of currently active threads (integer)

See:

- getFreeThreads()
- getMaxThreads()
- maxThreads

### getActiveUsers

    Array getActiveUsers()

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

Returns:

Array of User objects

See:

- getUser()
- getRegisteredUsers()
- registerUser()

### getAppDir

    String getAppDir()

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.

Returns:

String with the absolut path to the application directory

See:

- getDir()
- getServerDir()

### getCacheUsage

    Number getCacheUsage()

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

Returns:

Number of cached objects

See:

- clearCache()

### getCronJobs

    Object getCronJobs()

Returns an object of scheduled cron jobs.
Returns a JavaScript object with the function names as property names and the Packages.helma.util.CronJob instance as property values.

Returns:

Object with Packages.helma.util.CronJob properties

See:

- addCronJob()
- removeCronJob()

### getDir

    String getDir()

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.

Returns:

String with the absolut path to the application directory

See:

- getAppDir()
- getServerDir()

### getErrorCount

    Number getErrorCount()

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

Returns:

Number of errors (integer)

See:

- getUpSince()

### getFreeThreads

    Number getFreeThreads()

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

Returns:

Number of free threads (integer)

See:

- getMaxThreads()
- getActiveThreads()
- maxThreads

### getMaxThreads

    Number getMaxThreads()

Returns the maximum number of threads (i.e. request evaluators).

Returns:

Number of threads (integer)

See:

- getActiveThreads()
- getFreeThreads()
- maxThreads

### getName

    String getName()

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

Returns:

String with application's name

### getRegisteredUsers

    Array getRegisteredUsers()

Returns an array of all existing users.

Returns:

Array of User objects

See:

- getActiveUsers()
- getUser()
- registerUser()

### getRequestCount

    Number getRequestCount()

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

Returns:

Number of web requests served (integer)

See:

- getUpSince()

### getServerDir

    String getServerDir()

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.

Returns:

String with absolute path to home directory

See:

- getAppDir()
- getDir()

### getSession

    SessionObject getSession(<String> sessionID)

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

Parameters:

`sessionID` - as String, the ID of an existing session

Returns:

SessionObject matching the specified ID or null if there is no matching session

See:

- countSessions()
- createSession()
- getSessions()
- getSessionsForUser()

### getSessions

    Array getSessions()

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

Returns:

Array of SessionObject

See:

- countSessions()
- createSession()
- getSession()
- getSessionsForUser()

### getSessionsForUser

    Array getSessionsForUser(<User> user)

Returns an array of active sessions for the specified user
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.
Passing a string of the username as argument has been deprecated in favor of passing a User object.

Parameters:

`user` - as User object

Returns:

Array of SessionObject

See:

- countSessions()
- createSession()
- getSession()
- getSessions()

### getSkinfiles

    Map getSkinfiles()

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.

Returns:

Map of SkinMap objects

### getUpSince

    Date getUpSince()

Returns the timestamp of when that application has been started.

Returns:

Date when the application last started

See:

- getErrorCount()

### getUser

    User getUser(<String> username)

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.

Parameters:

`username` - as String

Returns:

User object with the specified _name property

See:

- getActiveUsers()
- getRegisteredUsers()
- registerUser()

### getXmlrpcCount

    Number getXmlrpcCount()

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

Returns:

Number of XmlRpc requests served (integer)

See:

- getUpSince()

### invoke

    Object invoke(<Object> thisObject,<Function> fnc,<Array> args,<Number> timeout)

Trigger a synchronous Helma invocation.

Parameters:

`thisObject` - as Object, the object to invoke the function on, or null for global invocation

`fnc` - the function or function name to invoke

`args` - as Array, optional arguments to be passed to the function fnc

`timeout` - as Number, optional amount of milliseconds after which the invocation should be interrupted

Returns:

the value returned by the function fnc

See:

- invokeAsync()

Throws:

- Exception exception thrown by the function

### invokeAsync

    Object invokeAsync(<Object> thisObject,<Function> fnc,<Array> args,<Number> timeout)

Trigger an asynchronous Helma invocation.
This method returns immedately with an object that allows to track the result of the function invocation with the following methods and properties:

- running - true while the function is running, false afterwards
- result - the value returned by the function, if any
- exception - the exception thrown by the function, if any
- waitForResult() - wait indefinitely until invocation terminates and return the result
- waitForResult(t) - wait for the specified number of milliseconds for invocation to terminate and return the result

Parameters:

`thisObject` - as Object, the object to invoke the function on, or null for global invocation

`fnc` - the function or function name to invoke

`args` - as Array, optional arguments to be passed to the function fnc

`timeout` - as Number, optional amount of milliseconds after which the invocation should be interrupted

Returns:

Object with the properties described above

See:

- invoke()

### log

    void log(<String> filenameOrText,<String> text)

Writes a string to a log file.
Either the text provided as the first argument is written to the eventLog file or the text that is provided as the second argument is written to a log file who's name is specified as the first argument.
Writing to a file can be overriden by setting the property "logdir" in the server.properties or app.properties file to the value "console".
Example:

     app.debug("This message is written to the test application's event log.");
     app.debug("custom", "This message is written to the custom.log file.");

     File helma/log/test_event.log:
     [2006/07/11 17:08] This message is written to the test application's event log.

     File helma/log/custom.log:
     [2006/07/11 17:08] This message is written to the custom.log file.

Parameters:

`filenameOrText` - as String, the log filename to write to or the text to write to the eventLog file

`text` - as String the text to write, if the filename was specified as the first argument

See:

- debug()

### registerUser

    User registerUser(<String> username, <String> password)

Creates a new User object
Creates a new HopObject of prototype User, stores it persistently, and returns the created User object.
When mapping the User prototype to a relational database, the type.properties file must contain mappings for the '_name'-property (the username) and for a property named 'password'.

Parameters:

`username` - as String

`password` - as String

Returns:

User object that was created

See:

- getActiveUsers()
- getUser()
- getRegisteredUsers()

### removeCronJob

    void removeCronJob(<String> functionName)

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

Parameters:

`functionName` - as String

See:

- addCronJob()
- getCronJobs()

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

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