org.tentackle.appworx
Class WebApplication

java.lang.Object
  org.tentackle.appworx.AbstractApplication
      org.tentackle.appworx.WebApplication

public class WebApplication
extends AbstractApplication

Web Application.

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 WebApplication 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 AppUserInfo-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

WebApplication()
Creates an instance of a web application.

Method Summary

void	addSession(Object sessionKey, AppUserInfo userInfo) Adds a mapping between a session and a user info.
ConnectionManager	createConnectionManager() Creates the connection manager for the client sessions.
DbPool	createDbPool() Creates the logical DbPool.
protected void	doFinishStartup() Finishes the startup. The default implementation starts the modification thread, unless "--nomodthread" given, creates the connection manager, the Db pool, and the DbServer instance.
protected void	doLogin() Connects the server to the database backend.
protected void	doStop() Terminates the application gracefully.
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.
static WebApplication	getWebApplication() Gets the current web application instance.
void	putDb(Db db) Release a logical db connection.
void	removeSession(Object sessionKey) Removes a mapping between a session and a user info.
void	start(Properties props) Starts the application.
void	stop() Gracefully terminates the web application server.

Methods inherited from class org.tentackle.appworx.AbstractApplication

createContextDb, createDb, createModificationThread, createUserInfo, detectEE, detectJNLP, doConfigureApplication, doInitialize, getContextDb, getDb, getProperties, getProperty, getRunningApplication, getUser, getUser, getUserInfo, installPreferences, installSecurityManager, isDeployedByEE, isDeployedByJNLP, register, securityRulesChanged, setContextDb, setProperties, setUserInfo, unregister, updateUserId

Methods inherited from class java.lang.Object

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

Constructor Detail

WebApplication

public WebApplication()

Creates an instance of a web application.

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

ApplicationException - if failed

addSession

public void addSession(Object sessionKey,
                       AppUserInfo 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 ApplicationException

Starts the application.

Parameters:

props - the properties to configure the application

Throws:

ApplicationException - if startup failed

See Also:

AbstractApplication.setProperties(java.util.Properties)

stop

public void stop()

Gracefully terminates the web application server.

createConnectionManager

public ConnectionManager createConnectionManager()

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

Returns:

the connection manager

createDbPool

public DbPool createDbPool()

Creates the logical DbPool. 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 manager. 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

doLogin

protected void doLogin()
                throws 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:

ApplicationException

doFinishStartup

protected void doFinishStartup()
                        throws ApplicationException

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

Overrides:

doFinishStartup in class AbstractApplication

Throws:

ApplicationException

doStop

protected void doStop()

Terminates the application gracefully.