org.tentackle.app

Class WebApplication

java.lang.Object

org.tentackle.app.AbstractApplication

org.tentackle.app.WebApplication

All Implemented Interfaces:

DomainContextProvider, SessionManagerProvider, SessionPoolProvider, SessionProvider

public abstract class WebApplication
extends AbstractApplication
implements SessionPoolProvider, SessionManagerProvider

Web AbstractApplication.

Web applications usually run in a container such as glassfish or in case of JRuby/Rails in a pack of mongrels or a single webrick. Because we cannot make any assumptions about the threading model (single thread/single instance/single jvm as with JRuby/Webrick or full-blown multithreaded as in glassfish or half-way in between like JRuby with mongrel_jcluster) the WebAbstractApplication provides a logical Db-pool on top of multiplexed physical database connections. The initial size of the logical Db pool is 2 on 1 physical connection. This will not waste resources in single thread per JVM setups (like Rails/Webrick) but will dynamically grow otherwise.

Web applications need some mapping between sessions and SessionInfo-objects that in turn carry the user id and a SecurityManager. For the time of a web-roundtrip a logical Db is picked from the pool and associated with that user info (i.e. "session"). Notice that there may be more than one session per user (but each gets its own user info). That's why user infos are mapped by a session key object and not by the user id. Furthermore, depending on the container's session model, it is not sure that the container's session carries the user id at all.

Author:

harald

Constructor Summary

Constructors

Constructor and Description
WebApplication(String name) Creates an instance of a web application.

Method Summary

Modifier and Type	Method and Description
void	addSession(Object sessionKey, SessionInfo userInfo) Adds a mapping between a session and a user info.
protected void	configurePreferences()
SessionPool	createDbPool() Creates the logical SessionPool.
ConnectionManager	createSessionManager() Creates the connection cache for the client sessions.
protected void	doFinishStartup() Finishes the startup. The default implementation starts the modification thread, unless "--nomodthread" given, creates the connection cache, the Db pool, and the DbServer instance.
protected void	doLogin() Connects the server to the database backend.
protected void	doStop(int exitValue) Terminates the application server.
protected void	doStop(int exitValue, Exception ex) Terminates the application server.
Db	getDb(Object sessionKey) Gets a logical db connection by a session key.
static WebApplication	getInstance(Class<? extends WebApplication> clazz, Properties props) Gets the current web application instance or starts a new instance if not already running.
SessionPool	getSessionPool()
static WebApplication	getWebApplication() Gets the current web application instance.
boolean	isServer() Returns whether the application is a server.
void	putDb(Db db) Release a logical db connection.
void	removeSession(Object sessionKey) Removes a mapping between a session and a user info.
void	setSessionInfo(SessionInfo sessionInfo)
void	start(Properties props) Starts the application.
void	stop() Gracefully terminates the web application server.

Methods inherited from class org.tentackle.app.AbstractApplication

configurePdoTracker, configureSecurityManager, createDomainContext, createSession, createSessionInfo, detectContainer, detectJNLP, doConfigureApplication, doInitialize, getCreationTime, getDomainContext, getName, getProperties, getProperty, getRunningApplication, getSession, getSessionInfo, getUser, getUser, isDeployedByJNLP, isRunningInContainer, logStackdump, register, setDomainContext, setName, setProperties, toString, unregister, updateSessionInfoAfterLogin

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.tentackle.pdo.SessionManagerProvider

getSessionManager

Methods inherited from interface org.tentackle.pdo.DomainContextProvider

on, opn

Constructor Detail

WebApplication

public WebApplication(String name)

Creates an instance of a web application.

Parameters:

name - the application name

Method Detail

getWebApplication

public static WebApplication getWebApplication()

Gets the current web application instance.

This is just a convenience method to AbstractApplication.getRunningApplication().

Returns:

the application, null if not started yet

getInstance

public static WebApplication getInstance(Class<? extends WebApplication> clazz,
                                         Properties props)
                                  throws org.tentackle.misc.ApplicationException

Gets the current web application instance or starts a new instance if not already running.

Web containers should use this method to make sure that only one instance is started per JVM/classloader-context.

If the application runs in a container (tomcat, glassfish, etc...) additional properties may be appended/overwritten to/in the given props-argument. In web.xml add the following lines:

       <env-entry>
          <env-entry-name>tentackle.properties</env-entry-name>
          <env-entry-value>../myapplication.properties</env-entry-value>
          <env-entry-type>java.lang.String</env-entry-type>
        </env-entry>
 

This will load the properties-file myapplication.properties from the WEB-INF-directory (without "../" from WEB-INF/classes) and modify the properties given by props.

Parameters:

clazz - the application class

props - the properties to configure the application

Returns:

the application

Throws:

org.tentackle.misc.ApplicationException - if failed

setSessionInfo

public void setSessionInfo(SessionInfo sessionInfo)

Overwridden to protect the sessioninfo once it is set.

Overrides:

setSessionInfo in class AbstractApplication

isServer

public boolean isServer()

Returns whether the application is a server.

Specified by:

isServer in class AbstractApplication

Returns:

true

configurePreferences

protected void configurePreferences()

Overrides:

configurePreferences in class AbstractApplication

addSession

public void addSession(Object sessionKey,
                       SessionInfo userInfo)

Adds a mapping between a session and a user info. This is usually done in the login controller. If a session with that key already exists, the user info will be replaced.

Parameters:

sessionKey - the (unique) session key

userInfo - the user info

removeSession

public void removeSession(Object sessionKey)

Removes a mapping between a session and a user info. This is usually done in the logout controller. If there is no such session, the method will do nothing.

Parameters:

sessionKey - the (unique) session key

getDb

public Db getDb(Object sessionKey)

Gets a logical db connection by a session key.

Parameters:

sessionKey - the session key

Returns:

the attached Db or null if no such session

putDb

public void putDb(Db db)

Release a logical db connection. Should be invoked after sending/rendering the response to the web browser.

Parameters:

db - the db to release

start

public void start(Properties props)
           throws org.tentackle.misc.ApplicationException

Starts the application.

Parameters:

props - the properties to configure the application

Throws:

org.tentackle.misc.ApplicationException - if startup failed

See Also:

AbstractApplication.setProperties(java.util.Properties)

stop

public void stop()
          throws org.tentackle.misc.ApplicationException

Gracefully terminates the web application server.

Throws:

org.tentackle.misc.ApplicationException - if termination failed

createSessionManager

public ConnectionManager createSessionManager()

Creates the connection cache for the client sessions. The default creates an MpxConnectionManager with initially 1 open connection, max 100.

Returns:

the connection cache

createDbPool

public SessionPool createDbPool()

Creates the logical SessionPool. The default implementation creates a DefaultDbPool with a 2 pre-opened Db, increment by 1, don't drop below 2. The maximum number of Db instances is derived from the connection cache. Because of the nature of web applications, it doesn't make sense to allow more Db instances than connections (web sessions are short lived as opposed to desktop sessions).

Returns:

the database pool, null if don't use a pool

getSessionPool

public SessionPool getSessionPool()

Specified by:

getSessionPool in interface SessionPoolProvider

doLogin

protected void doLogin()
                throws org.tentackle.misc.ApplicationException

Connects the server to the database backend. The database properties may be either given by the "db" property or if this is missing the application's properties will be used.

Throws:

org.tentackle.misc.ApplicationException - if login failed

doFinishStartup

protected void doFinishStartup()
                        throws org.tentackle.misc.ApplicationException

Finishes the startup.
The default implementation starts the modification thread, unless "--nomodthread" given, creates the connection cache, the Db pool, and the DbServer instance.

Overrides:

doFinishStartup in class AbstractApplication

Throws:

org.tentackle.misc.ApplicationException - if failed

doStop

protected void doStop(int exitValue,
                      Exception ex)

Terminates the application server.

Parameters:

exitValue - the doStop value for System.exit()

ex - an exception causing the termination, null if none

doStop

protected void doStop(int exitValue)

Terminates the application server.

Parameters:

exitValue - the doStop value for System.exit()