org.tentackle.web.app

Class WebApplication<T>

java.lang.Object

org.tentackle.app.AbstractApplication

org.tentackle.web.app.WebApplication<T>

Type Parameters:

T - the web session key type

All Implemented Interfaces:

org.tentackle.dbms.ConnectionManagerProvider, org.tentackle.pdo.DomainContextProvider, org.tentackle.session.SessionPoolProvider, org.tentackle.session.SessionProvider

public abstract class WebApplication<T>
extends org.tentackle.app.AbstractApplication
implements org.tentackle.session.SessionPoolProvider, org.tentackle.dbms.ConnectionManagerProvider

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	addWebSession(T sessionKey, org.tentackle.session.SessionInfo userInfo) Adds a mapping between a web session key and a user session info. This is usually done in the login controller.
protected void	configurePreferences()
protected void	configureSessionInfo(org.tentackle.session.SessionInfo sessionInfo) Configures the session info.
org.tentackle.dbms.ConnectionManager	createConnectionManager() Creates the connection cache for the client sessions.
org.tentackle.session.SessionPool	createSessionPool() Creates the logical SessionPool. The default implementation creates a DefaultDbPool with a 2 pre-opened Db, increment by 1, don't drop below 2.
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.
org.tentackle.dbms.ConnectionManager	getConnectionManager() Gets the connection manager.
static <T> WebApplication<T>	getInstance(Class<? extends WebApplication<T>> clazz, Properties props) Gets the current web application instance or starts a new instance if not already running.
org.tentackle.session.Session	getSession(T sessionKey) Gets a persistence session from the session pool by a web session key.
Collection<T>	getSessionKeys(org.tentackle.session.SessionInfo sessionInfo) Gets the web session keys for a user session info.
org.tentackle.session.SessionPool	getSessionPool()
static <T> WebApplication<T>	getWebApplication() Gets the current web application instance.
boolean	isServer() Returns whether the application is a server.
void	putSession(org.tentackle.session.Session session) Release a persistence session. Should be invoked after sending/rendering the response to the web browser.
void	removeWebSession(T sessionKey) Removes a mapping between a web session key and a user session info. This is usually done in the logout controller.
void	setSessionInfo(org.tentackle.session.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

configureModificationTracker, configureSecurityManager, createDomainContext, createSession, createSessionInfo, deregisterJdbcDrivers, 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.DomainContextProvider

on, op

Constructor Detail

WebApplication

public WebApplication(String name)

Creates an instance of a web application.

Parameters:

name - the application name

Method Detail

getWebApplication

public static <T> WebApplication<T> getWebApplication()

Gets the current web application instance.

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

Type Parameters:

T - the web session key type

Returns:

the application, null if not started yet

getInstance

public static <T> WebApplication<T> getInstance(Class<? extends WebApplication<T>> 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.

Type Parameters:

T - the web session key type

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(org.tentackle.session.SessionInfo sessionInfo)

Overwridden to protect the sessioninfo once it is set.

Overrides:

setSessionInfo in class org.tentackle.app.AbstractApplication

isServer

public boolean isServer()

Returns whether the application is a server.

Specified by:

isServer in class org.tentackle.app.AbstractApplication

Returns:

true

configurePreferences

protected void configurePreferences()

Overrides:

configurePreferences in class org.tentackle.app.AbstractApplication

addWebSession

public void addWebSession(T sessionKey,
                          org.tentackle.session.SessionInfo userInfo)

Adds a mapping between a web session key and a user session 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) web session key

userInfo - the user info

removeWebSession

public void removeWebSession(T sessionKey)

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

Parameters:

sessionKey - the (unique) web session key

getSessionKeys

public Collection<T> getSessionKeys(org.tentackle.session.SessionInfo sessionInfo)

Gets the web session keys for a user session info.

Parameters:

sessionInfo - the user session info

Returns:

the web session keys, never null

getSession

public org.tentackle.session.Session getSession(T sessionKey)

Gets a persistence session from the session pool by a web session key.

Parameters:

sessionKey - the web session key

Returns:

the attached session or null if no such session

putSession

public void putSession(org.tentackle.session.Session session)

Release a persistence session.
Should be invoked after sending/rendering the response to the web browser.

Parameters:

session - the persistence session 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

createConnectionManager

public org.tentackle.dbms.ConnectionManager createConnectionManager()

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

Returns:

the connection cache

getConnectionManager

public org.tentackle.dbms.ConnectionManager getConnectionManager()

Gets the connection manager.

Specified by:

getConnectionManager in interface org.tentackle.dbms.ConnectionManagerProvider

Returns:

the connection manager.

createSessionPool

public org.tentackle.session.SessionPool createSessionPool()

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 org.tentackle.session.SessionPool getSessionPool()

Specified by:

getSessionPool in interface org.tentackle.session.SessionPoolProvider

configureSessionInfo

protected void configureSessionInfo(org.tentackle.session.SessionInfo sessionInfo)

Configures the session info.

Parameters:

sessionInfo - the session info

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 org.tentackle.app.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()