app

Object
   |
   +--app

__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

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()