Package helma.framework.core

# Class Application

java.lang.Object
helma.framework.core.Application

All Implemented Interfaces:
  `Runnable`

public final class Application extends Object implements Runnable
The central class of a Helma application. This class keeps a pool of request evaluators (threads with JavaScript interpreters), waits for requests from the Web server or XML-RPC port and dispatches them to the evaluators.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected Vector`
`allThreads`
`protected INode`
`cachenode`
`boolean`
`caseInsensitive`
`protected long`
`errorCount`
`protected Stack`
`freeThreads`
Collections for evaluator thread pooling
`protected NodeManager`
`nmgr`
`protected long`
`requestCount`
`protected SkinManager`
`skinmgr`
The skin manager for this application
`TypeManager`
`typemgr`
The type manager checks if anything in the application's prototype definitions has been updated prior to each evaluation.
`protected long`
`xmlrpcCount`

## Constructor Summary

Constructors
Constructor
Description
`Application(String name)`
Simple constructor for dead application instances.
`Application(String name, Repository[] repositories, File dbDir)`
Build an application with the given name with the given sources.
`Application(String name, Server server)`
Build an application with the given name and server instance.
`Application(String name, Server server, Repository[] repositories, File customAppDir, File customDbDir)`
Build an application with the given name, server instance, sources and db directory.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`addRepository(Repository rep, Repository current)`
Add a repository to this app's repository list.
`boolean`
`authenticate(String uname, String password)`
In contrast to login, this works outside the Hop user object framework.
`protected void`
`checkXmlRpcAccess(String proto, String method)`
Check if a method may be invoked via XML-RPC on a prototype.
`void`
`clearCache()`
Reset the application's object cache, causing all objects to be refetched from the database.
`String`
`correctPropertyName(String propName)`
Returns the correct property name which is either case sensitive or case insensitive
`int`
`countActiveEvaluators()`
`int`
`countEvaluators()`
`int`
`countFreeEvaluators()`
`int`
`countMaxActiveEvaluators()`
`int`
`countSessions()`
Returns the number of currenty active sessions.
`int`
`countThreads()`
`Session`
`createSession(String sessionId)`
Return the session currently associated with a given Hop session ID.
`boolean`
`debug()`
Tell other classes whether they should output logging information for this application.
`Prototype`
`definePrototype(String name, Map typeProps)`
Programmatically define a new prototype.
`ResponseTrans`
`execute(RequestTrans req)`
Execute a request coming in from a web client.
`Object`
`executeExternal(String method, Vector args)`
`Object`
`executeXmlRpc(String method, Vector args)`
Called to execute a method via XML-RPC, usally by helma.main.ApplicationManager which acts as default handler/request dispatcher.
`org.apache.commons.logging.Log`
`getAccessLog()`
get the app's access log.
`int`
`getActiveThreads()`
Return the number of currently active threads
`List`
`getActiveUsers()`
Return a list of Helma nodes (HopObjects - the database object representing the user, not the session object) representing currently logged in users.
`File`
`getAppDir()`
Get the application directory.
`String`
`getBaseURI()`
Returns the baseURI for Hrefs in this application.
`INode`
`getCacheNode()`
Return a transient node that is shared by all evaluators of this application ("app node")
`Map`
`getCacheStatistics()`
Returns a map of cache statistics
`int`
`getCacheUsage()`
Returns the number of elements in the NodeManager's cache
`String`
`getCharset()`
Return the name of the character encoding used by this application
`long`
`getChecksum()`
Get a checksum that mirrors the state of this application in the sense that if anything in the applciation changes, the checksum hopefully will change, too.
`Object`
`getChildElement(Object obj, String name)`
Retrieve a child element of this object by name.
`ClassLoader`
`getClassLoader()`
Return the application's classloader
`Resource`
`getCurrentCodeResource()`
Set the code resource currently being evaluated/compiled.
`RequestEvaluator`
`getCurrentRequestEvaluator()`
Get the current RequestEvaluator, or null if the calling thread is not evaluating a request.
`Object`
`getDataRoot()`
This method returns the root object of this application's object tree.
`protected Object`
`getDataRoot(ScriptingEngine engine)`
This method returns the root object of this application's object tree.
`DbMapping`
`getDbMapping(String typename)`
Get the DbMapping associated with a prototype name in this application
`ResourceProperties`
`getDbProperties()`
Get the application's db properties
`DbSource`
`getDbSource(String name)`
Return a DbSource object for a given name.
`String`
`getElementName(Object obj)`
Return the name to be used to get this element from its parent
`long`
`getErrorCount()`
`RequestEvaluator`
`getEvaluator()`
Returns a free evaluator to handle a request.
`org.apache.commons.logging.Log`
`getEventLog()`
get the app's event log.
`String`
`getHrefRootPrototype()`
Returns the prototype name that Hrefs in this application should start with.
`String`
`getJavaClassForPrototype(String typename)`
Return the java class that a given prototype wraps, or null.
`org.apache.commons.logging.Log`
`getLogger(String logname)`
Get a logger object to log events for this application.
`String`
`getName()`
Return the name of this application
`String`
`getNodeHref(Object elem, String actionName, Map queryParams)`
Return a path to be used in a URL pointing to the given element and action
`NodeManager`
`getNodeManager()`
Returns the node manager for this application.
`Object`
`getParentElement(Object obj)`
Return the parent element of this object.
`ResourceProperties`
`getProperties()`
Get the application's app properties
`String`
`getProperty(String propname)`
Proxy method to get a property from the applications properties.
`String`
`getProperty(String propname, String defvalue)`
Proxy method to get a property from the applications properties.
`Prototype`
`getPrototype(Object obj)`
Return a prototype for a given node.
`Prototype`
`getPrototypeByName(String name)`
Return the prototype with the given name, if it exists
`String`
`getPrototypeName(Object obj)`
Get the name of the prototype to be used for this object.
`Collection`
`getPrototypes()`
Return a collection containing all prototypes defined for this application
`List`
`getRegisteredUsers()`
Return a list of Helma nodes (HopObjects - the database object representing the user, not the session object) representing registered users of this application.
`List`
`getRepositories()`
Returns the repositories of this application
`int`
`getRepositoryIndex(Repository rep)`
Searches for the index of the given repository for this app.
`long`
`getRequestCount()`
`ResourceComparator`
`getResourceComparator()`
Get a comparator for comparing Resources according to the order of repositories they're contained in.
`String`
`getRootHref()`
Return the href to the root of this application.
`String`
`getRootId()`
Return the id of the object to be used as this application's root object
`DbMapping`
`getRootMapping()`
Return the prototype of the object to be used as this application's root object
`File`
`getServerDir()`
Return the directory of the Helma server
`Session`
`getSession(String sessionId)`
Return the session currently associated with a given Hop session ID.
`SessionManager`
`getSessionManager()`
Return the application's session manager
`Map`
`getSessions()`
Return the whole session map.
`List`
`getSessionsForUsername(String username)`
Return an array of `SessionBean` objects currently associated with a given Helma user.
`Skin`
`getSkin(String protoname, String skinname, Object[] skinpath)`
Return a skin for a given object.
`long`
`getStarttime()`
`UploadStatus`
`getUploadStatus(RequestTrans req)`
Return the current upload status.
`INode`
`getUserNode(String uid)`
Returns a Node representing a registered user of this application by his or her user name.
`INode`
`getUserRoot()`
Returns the Object which contains registered users of this application.
`WrappedNodeManager`
`getWrappedNodeManager()`
Returns a wrapper containing the node manager for this application.
`long`
`getXmlrpcCount()`
`String`
`getXmlRpcHandlerName()`
Return the XML-RPC handler name for this app.
`boolean`
`hasExplicitBaseURI()`
Return true if the baseURI property is defined in the application properties, false otherwise.
`void`
`init()`
Get the application ready to run, initializing the evaluators and type manager.
`void`
`init(String ignoreDirs)`
Get the application ready to run, initializing the evaluators and type manager.
`boolean`
`isJavaPrototype(String typename)`
Check whether a prototype is for scripting a java class, i.e.
`boolean`
`isRunning()`
Returns true if this app is currently running
`void`
`logAccess(String msg)`
Log an application access
`void`
`logDebug(String msg)`
Log a generic application debug message
`void`
`logError(String msg)`
Log an application error
`void`
`logError(String msg, Throwable error)`
Log an application error
`void`
`logEvent(String msg)`
Log a generic application event
`boolean`
`loginSession(String uname, String password, Session session)`
Log in a user given his or her user name and password.
`void`
`logoutSession(Session session)`
Log out a session from this application.
`void`
`printThreadStats()`
Periodically called to log thread stats for this application
`INode`
`registerUser(String uname, String password)`
Register a user with the given user name and password.
`void`
`releaseEvaluator(RequestEvaluator ev)`
Returns an evaluator back to the pool when the work is done.
`void`
`run()`
The run method performs periodic tasks like executing the scheduler method and kicking out expired user sessions.
`void`
`setBaseURI(String uri)`
This method sets the base URL of this application which will be prepended to the actual object path.
`void`
`setCurrentCodeResource(Resource resource)`
Set the code resource currently being evaluated/compiled.
`protected void`
`setCurrentRequestEvaluator(RequestEvaluator eval)`
Set the current RequestEvaluator for the calling thread.
`void`
`setDataRoot(Object root)`
Set the application's root element to an arbitrary object.
`boolean`
`setNumberOfEvaluators(int n)`
This can be used to set the maximum number of evaluators which will be allocated.
`void`
`start()`
Create and start scheduler and cleanup thread
`void`
`stop()`
This is called to shut down a running application.
`String`
`toString()`
Return a string representation for this app.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

## Field Details

### caseInsensitive

public boolean caseInsensitive

### nmgr

protected NodeManager nmgr

### typemgr

public TypeManager typemgr
The type manager checks if anything in the application's prototype definitions has been updated prior to each evaluation.

### skinmgr

protected SkinManager skinmgr
The skin manager for this application

### freeThreads

protected Stack freeThreads
Collections for evaluator thread pooling

### allThreads

protected Vector allThreads

### cachenode

protected INode cachenode

### requestCount

protected volatile long requestCount

### xmlrpcCount

protected volatile long xmlrpcCount

### errorCount

protected volatile long errorCount

## Constructor Details

### Application

public Application(String name)
Simple constructor for dead application instances.

### Application

public Application(String name, Repository[] repositories, File dbDir) throws RemoteException, IllegalArgumentException
Build an application with the given name with the given sources. No Server-wide properties are created or used.

Throws:
  `RemoteException`
  `IllegalArgumentException`

### Application

public Application(String name, Server server) throws RemoteException, IllegalArgumentException
Build an application with the given name and server instance. The app directories will be created if they don't exist already.

Throws:
  `RemoteException`
  `IllegalArgumentException`

### Application

public Application(String name, Server server, Repository[] repositories, File customAppDir, File customDbDir) throws RemoteException, IllegalArgumentException
Build an application with the given name, server instance, sources and db directory.

Throws:
  `RemoteException`
  `IllegalArgumentException`

## Method Details

### init

public void init() throws DatabaseException, IllegalAccessException, InstantiationException, ClassNotFoundException, InterruptedException
Get the application ready to run, initializing the evaluators and type manager.

Throws:
  `DatabaseException`
  `IllegalAccessException`
  `InstantiationException`
  `ClassNotFoundException`
  `InterruptedException`

### init

public void init(String ignoreDirs) throws DatabaseException, IllegalAccessException, InstantiationException, ClassNotFoundException, InterruptedException
Get the application ready to run, initializing the evaluators and type manager.

Parameters:
  `ignoreDirs` - comma separated list of directory names to ignore
Throws:
  `DatabaseException`
  `IllegalAccessException`
  `InstantiationException`
  `ClassNotFoundException`
  `InterruptedException`

### start

public void start()
Create and start scheduler and cleanup thread

### stop

public void stop()
This is called to shut down a running application.

### isRunning

public boolean isRunning()
Returns true if this app is currently running

Returns:
  true if the app is running

### getAppDir

public File getAppDir()
Get the application directory.

Returns:
  the application directory, or first file based repository

### getResourceComparator

public ResourceComparator getResourceComparator()
Get a comparator for comparing Resources according to the order of repositories they're contained in.

Returns:
  a comparator that sorts resources according to their repositories

### getEvaluator

public RequestEvaluator getEvaluator()
Returns a free evaluator to handle a request.

### releaseEvaluator

public void releaseEvaluator(RequestEvaluator ev)
Returns an evaluator back to the pool when the work is done.

### setNumberOfEvaluators

public boolean setNumberOfEvaluators(int n)
This can be used to set the maximum number of evaluators which will be allocated. If evaluators are required beyound this number, an error will be thrown.

### getActiveThreads

public int getActiveThreads()
Return the number of currently active threads

### execute

public ResponseTrans execute(RequestTrans req)
Execute a request coming in from a web client.

### executeXmlRpc

public Object executeXmlRpc(String method, Vector args) throws Exception
Called to execute a method via XML-RPC, usally by helma.main.ApplicationManager which acts as default handler/request dispatcher.

Throws:
  `Exception`

### executeExternal

public Object executeExternal(String method, Vector args) throws Exception

Throws:
  `Exception`

### clearCache

public void clearCache()
Reset the application's object cache, causing all objects to be refetched from the database.

### getCacheUsage

public int getCacheUsage()
Returns the number of elements in the NodeManager's cache

### getCacheStatistics

public Map getCacheStatistics()
Returns a map of cache statistics

### setDataRoot

public void setDataRoot(Object root)
Set the application's root element to an arbitrary object. After this is called with a non-null object, the helma node manager will be bypassed. This function can be used to script and publish any Java object structure with Helma.

### getDataRoot

public Object getDataRoot() throws Exception
This method returns the root object of this application's object tree.

Throws:
  `Exception`

### getDataRoot

protected Object getDataRoot(ScriptingEngine engine) throws Exception
This method returns the root object of this application's object tree.

Throws:
  `Exception`

### getRootMapping

public DbMapping getRootMapping()
Return the prototype of the object to be used as this application's root object

### getRootId

public String getRootId()
Return the id of the object to be used as this application's root object

### getUserRoot

public INode getUserRoot()
Returns the Object which contains registered users of this application.

### getNodeManager

public NodeManager getNodeManager()
Returns the node manager for this application. The node manager is the gateway to the helma.objectmodel packages, which perform the mapping of objects to relational database tables or the embedded database.

### getWrappedNodeManager

public WrappedNodeManager getWrappedNodeManager()
Returns a wrapper containing the node manager for this application. The node manager is the gateway to the helma.objectmodel packages, which perform the mapping of objects to relational database tables or the embedded database.

### getSessionManager

public SessionManager getSessionManager()
Return the application's session manager

Returns:
  the SessionManager instance used by this app

### getCacheNode

public INode getCacheNode()
Return a transient node that is shared by all evaluators of this application ("app node")

### getUserNode

public INode getUserNode(String uid)
Returns a Node representing a registered user of this application by his or her user name.

### getPrototype

public Prototype getPrototype(Object obj)
Return a prototype for a given node. If the node doesn't specify a prototype, return the generic hopobject prototype.

### getPrototypeByName

public Prototype getPrototypeByName(String name)
Return the prototype with the given name, if it exists

### getPrototypes

public Collection getPrototypes()
Return a collection containing all prototypes defined for this application

### definePrototype

public Prototype definePrototype(String name, Map typeProps)
Programmatically define a new prototype. If a prototype with this name already exists return the existing prototype.

Parameters:
  `name` - the prototype name
  `typeProps` - custom type properties map
Returns:
  the new prototype

### getSkin

public Skin getSkin(String protoname, String skinname, Object[] skinpath) throws IOException
Return a skin for a given object. The skin is found by determining the prototype to use for the object, then looking up the skin for the prototype.

Throws:
  `IOException`

### createSession

public Session createSession(String sessionId)
Return the session currently associated with a given Hop session ID. Create a new session if necessary.

### getActiveUsers

public List getActiveUsers()
Return a list of Helma nodes (HopObjects - the database object representing the user, not the session object) representing currently logged in users.

### getRegisteredUsers

public List getRegisteredUsers()
Return a list of Helma nodes (HopObjects - the database object representing the user, not the session object) representing registered users of this application.

### getSessionsForUsername

public List getSessionsForUsername(String username)
Return an array of `SessionBean` objects currently associated with a given Helma user.

### getSession

public Session getSession(String sessionId)
Return the session currently associated with a given Hop session ID.

### getSessions

public Map getSessions()
Return the whole session map.

### countSessions

public int countSessions()
Returns the number of currenty active sessions.

### registerUser

public INode registerUser(String uname, String password)
Register a user with the given user name and password.

### loginSession

public boolean loginSession(String uname, String password, Session session)
Log in a user given his or her user name and password.

### logoutSession

public void logoutSession(Session session)
Log out a session from this application.

### authenticate

public boolean authenticate(String uname, String password)
In contrast to login, this works outside the Hop user object framework. Instead, the user is authenticated against a passwd file in the application directory. This is to have some sort of authentication available *before* the application is up and running, i.e. for application setup tasks.

### getRootHref

public String getRootHref() throws UnsupportedEncodingException
Return the href to the root of this application.

Returns:
  the root element's URL
Throws:
  `UnsupportedEncodingException` - if the application's charset property is not a valid encoding name

### getNodeHref

public String getNodeHref(Object elem, String actionName, Map queryParams) throws UnsupportedEncodingException
Return a path to be used in a URL pointing to the given element and action

Parameters:
  `elem` - the object to get the URL for
  `actionName` - an optional action name
  `queryParams` - optional map of query parameters
Returns:
  the element's URL
Throws:
  `UnsupportedEncodingException` - if the application's charset property is not a valid encoding name

### getBaseURI

public String getBaseURI()
Returns the baseURI for Hrefs in this application.

### setBaseURI

public void setBaseURI(String uri)
This method sets the base URL of this application which will be prepended to the actual object path.

### hasExplicitBaseURI

public boolean hasExplicitBaseURI()
Return true if the baseURI property is defined in the application properties, false otherwise.

### getHrefRootPrototype

public String getHrefRootPrototype()
Returns the prototype name that Hrefs in this application should start with.

### debug

public boolean debug()
Tell other classes whether they should output logging information for this application.

### getCurrentRequestEvaluator

public RequestEvaluator getCurrentRequestEvaluator()
Get the current RequestEvaluator, or null if the calling thread is not evaluating a request.

Returns:
  the RequestEvaluator belonging to the current thread

### setCurrentRequestEvaluator

protected void setCurrentRequestEvaluator(RequestEvaluator eval)
Set the current RequestEvaluator for the calling thread.

Parameters:
  `eval` - the RequestEvaluator belonging to the current thread

### correctPropertyName

public String correctPropertyName(String propName)
Returns the correct property name which is either case sensitive or case insensitive

Parameters:
  `propName` - the raw property name
Returns:
  the correct property name

### getClassLoader

public ClassLoader getClassLoader()
Return the application's classloader

### getElementName

public String getElementName(Object obj)
Return the name to be used to get this element from its parent

### getChildElement

public Object getChildElement(Object obj, String name)
Retrieve a child element of this object by name.

### getParentElement

public Object getParentElement(Object obj)
Return the parent element of this object.

### getPrototypeName

public String getPrototypeName(Object obj)
Get the name of the prototype to be used for this object. This will determine which scripts, actions and skins can be called on it within the Helma scripting and rendering framework.

### logError

public void logError(String msg, Throwable error)
Log an application error

### logError

public void logError(String msg)
Log an application error

### logEvent

public void logEvent(String msg)
Log a generic application event

### logDebug

public void logDebug(String msg)
Log a generic application debug message

### logAccess

public void logAccess(String msg)
Log an application access

### getEventLog

public org.apache.commons.logging.Log getEventLog()
get the app's event log.

### getAccessLog

public org.apache.commons.logging.Log getAccessLog()
get the app's access log.

### getLogger

public org.apache.commons.logging.Log getLogger(String logname)
Get a logger object to log events for this application.

### run

public void run()
The run method performs periodic tasks like executing the scheduler method and kicking out expired user sessions.

Specified by:
  `run` in interface `Runnable`

### isJavaPrototype

public boolean isJavaPrototype(String typename)
Check whether a prototype is for scripting a java class, i.e. if there's an entry for it in the class.properties file.

### getJavaClassForPrototype

public String getJavaClassForPrototype(String typename)
Return the java class that a given prototype wraps, or null.

### getDbSource

public DbSource getDbSource(String name)
Return a DbSource object for a given name. A DbSource is a relational database defined in a db.properties file.

### getName

public String getName()
Return the name of this application

### addRepository

public boolean addRepository(Repository rep, Repository current)
Add a repository to this app's repository list. This is used for ZipRepositories contained in top-level file repositories, for instance.

Parameters:
  `rep` - the repository to add
  `current` - the current/parent repository
Returns:
  if the repository was not yet contained

### getRepositoryIndex

public int getRepositoryIndex(Repository rep)
Searches for the index of the given repository for this app. The arguement must be a root argument, or -1 will be returned.

Parameters:
  `rep` - one of this app's root repositories.
Returns:
  the index of the first occurrence of the argument in this list; returns `-1` if the object is not found.

### getRepositories

public List getRepositories()
Returns the repositories of this application

Returns:
  iterator through application repositories

### setCurrentCodeResource

public void setCurrentCodeResource(Resource resource)
Set the code resource currently being evaluated/compiled. This is used to set the proper parent repository when a new repository is added via app.addRepository().

Parameters:
  `resource` - the resource being currently evaluated/compiled

### getCurrentCodeResource

public Resource getCurrentCodeResource()
Set the code resource currently being evaluated/compiled. This is used to set the proper parent repository when a new repository is added via app.addRepository().

Returns:
  the resource being currently evaluated/compiled

### getServerDir

public File getServerDir()
Return the directory of the Helma server

### getDbMapping

public DbMapping getDbMapping(String typename)
Get the DbMapping associated with a prototype name in this application

### getUploadStatus

public UploadStatus getUploadStatus(RequestTrans req)
Return the current upload status.

Parameters:
  `req` - the upload RequestTrans
Returns:
  the current upload status.

### getChecksum

public long getChecksum()
Get a checksum that mirrors the state of this application in the sense that if anything in the applciation changes, the checksum hopefully will change, too.

### getProperty

public String getProperty(String propname)
Proxy method to get a property from the applications properties.

### getProperty

public String getProperty(String propname, String defvalue)
Proxy method to get a property from the applications properties.

### getProperties

public ResourceProperties getProperties()
Get the application's app properties

Returns:
  the properties reflecting the app.properties

### getDbProperties

public ResourceProperties getDbProperties()
Get the application's db properties

Returns:
  the properties reflecting the db.properties

### getXmlRpcHandlerName

public String getXmlRpcHandlerName()
Return the XML-RPC handler name for this app. The contract is to always return the same string, even if it has been changed in the properties file during runtime, so the app gets unregistered correctly.

### toString

public String toString()
Return a string representation for this app.

Overrides:
  `toString` in class `Object`

### countThreads

public int countThreads()

### countEvaluators

public int countEvaluators()

### countFreeEvaluators

public int countFreeEvaluators()

### countActiveEvaluators

public int countActiveEvaluators()

### countMaxActiveEvaluators

public int countMaxActiveEvaluators()

### getRequestCount

public long getRequestCount()

### getXmlrpcCount

public long getXmlrpcCount()

### getErrorCount

public long getErrorCount()

### getStarttime

public long getStarttime()

Returns:
  ...

### getCharset

public String getCharset()
Return the name of the character encoding used by this application

Returns:
  the character encoding

### printThreadStats

public void printThreadStats()
Periodically called to log thread stats for this application

### checkXmlRpcAccess

protected void checkXmlRpcAccess(String proto, String method) throws Exception
Check if a method may be invoked via XML-RPC on a prototype.

Throws:
  `Exception`