fc.web.servlet
Class WebApp

java.lang.Object
  extended by fc.web.servlet.WebApp
All Implemented Interfaces:
EventListener, javax.servlet.ServletContextListener

public class WebApp
extends Object
implements javax.servlet.ServletContextListener

Application level global object running within a servlet web application (i.e., a servlet context). Global webapp data can be stored/retrieved via the put/get methods.

Initializes and stores various variables useful for all servlets/pages running in our JVM. Implements ServletContextListener and initializes itself when informed by the servlet container's context initialization event.

It's optional to use this class. If it is used, it's configured by adding the following to the appropriate sections of WEB-INF/web.xml:

<context-param>
        <param-name>configfile</param-name>
        <param-value>app.conf</param-value>
</context-param>
<context-param>
          <param-name>appName</param-name>
          <param-value>some-arbitrary-string-unique-across-all-webapps</param-value>
</context-param>

<listener>
        <listener-class>fc.web.servlet.WebApp</listener-class>
</listener>

Important:If this class is used and its initialization is not successful, it tries to shut down the entire servlet JVM by calling System.exit. (The idea being it's better to fail early and safely then continue beyond this point).

If used, this class requires the following context configuration parameter:

This class can also be subclassed to initialize/contain website specific data and background/helper processing threads. Alternatively, along with this class as-is, additional independent site-specific ServletContextListener classes can be created and used as necessary.


Field Summary
 Map allServletsMap
          A (initially empty) Map that servlets can use to store a reference to themselves.
 Log appLog
          A Log object.
 Map appMap
           
 Map connectionManagers
           
 long default_dbcache_time
           
 ThreadLocalCalendar default_tlcal
           
 ThreadLocalDateFormat default_tldf
           
 ThreadLocalNumberFormat default_tlnf
           
 ThreadLocalRandom default_tlrand
           
 ConnectionMgr defaultConnectionManager
           
 PropertyMgr propertyMgr
           
 Map tlcalMap
           
 Map tldfMap
           
 Map tlMap
           
 Map tlnfMap
           
 Map tlrandMap
           
 
Constructor Summary
WebApp()
          A no-arg constructor public such that the servlet container can instantiate this class.
 
Method Summary
static WebApp addWebApp(javax.servlet.ServletContext context, String appName, String sconf)
          Add a new WebApp instance manually.
 void contextDestroyed(javax.servlet.ServletContextEvent sce)
          Basic implementation of the web application cleanup upon context destruction.
 void contextInitialized(javax.servlet.ServletContextEvent sce)
          Basic implementation of the web application cleanup upon context creation.
 Object get(Object key)
          Returns the specified object from the global application map or null if the object was not found.
 Log getAppLog()
           
 Connection getConnection()
           
 Connection getConnection(String databasename)
           
 ConnectionMgr getConnectionMgr()
          Returns the connection manager corresponding to the default database name.
 ConnectionMgr getConnectionMgr(String databasename)
          Returns the connection manager corresponding to the database name.
 Cache getDBCache()
          Convenience method to get the pre-created application cache.
 Form getForm(String name)
          Convenience method to return a form stored previously via the putForm method.
static WebApp getInstance(String appName)
           
 PropertyMgr getPropertyMgr()
          Returns the property manager associated with this WebApp (properties of the app configuration file can be read via this property mgr)
 ThreadLocalCalendar getThreadLocalCalendar()
          Returns the default ThreadLocalCalendar object (a new ThreadLocalCalendar is created if it does not exist).
 ThreadLocalCalendar getThreadLocalCalendar(String name)
          Returns the ThreadLocalCalendar object corresponding to the specified name (a new ThreadLocalCalendar is created if it does not exist).
 ThreadLocalDateFormat getThreadLocalDateFormat()
          Returns the default threadLocalDateFormat object (a new ThreadLocalDateFormat is created if it does not exist).
 ThreadLocalDateFormat getThreadLocalDateFormat(String name)
          Returns the ThreadLocalDateFormat object corresponding to the specified name (a new ThreadLocalDateFormat is created if it does not exist).
 ThreadLocalNumberFormat getThreadLocalNumberFormat()
          Returns the default ThreadLocalNumberFormat object (a new ThreadLocalNumberFormat is created if it does not exist).
 ThreadLocalNumberFormat getThreadLocalNumberFormat(String name)
          Returns the ThreadLocalNumberFormat object corresponding to the specified name (a new ThreadLocalNumberFormat is created if it does not exist).
 ThreadLocalObject getThreadLocalObject(String name)
          Returns the ThreadLocalObject corresponding to the specified name (a new ThreadLocalObject is created if it does not exist).
 ThreadLocalRandom getThreadLocalRandom()
          Returns the default ThreadLocalRandom object (a new ThreadLocalRandom is created if it does not exist).
 ThreadLocalRandom getThreadLocalRandom(String name)
          Returns the ThreadLocalRandom object corresponding to the specified name (a new ThreadLocalRandom is created if it does not exist).
 void put(Object key, Object val)
          Puts the specified key/object into the global application map.
 void putForm(Form f)
           
 void removeForm(String name)
           
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

connectionManagers

public Map connectionManagers

defaultConnectionManager

public ConnectionMgr defaultConnectionManager

default_dbcache_time

public long default_dbcache_time

default_tlcal

public ThreadLocalCalendar default_tlcal

default_tldf

public ThreadLocalDateFormat default_tldf

default_tlnf

public ThreadLocalNumberFormat default_tlnf

default_tlrand

public ThreadLocalRandom default_tlrand

appMap

public Map appMap

tlcalMap

public Map tlcalMap

tldfMap

public Map tldfMap

tlnfMap

public Map tlnfMap

tlrandMap

public Map tlrandMap

tlMap

public Map tlMap

appLog

public Log appLog
A Log object. Servlets typically create their own loggers (with servlet specific logging levels) but can alternatively use this default appLog. This appLog is used by non-servlet classes such as this class itself, various listeners etc.


propertyMgr

public PropertyMgr propertyMgr

allServletsMap

public Map allServletsMap
A (initially empty) Map that servlets can use to store a reference to themselves. This is required because the servlet API has deprecated a similar API call (the servlet API authors are brain damaged 'tards).

Constructor Detail

WebApp

public WebApp()
A no-arg constructor public such that the servlet container can instantiate this class.

Method Detail

getInstance

public static WebApp getInstance(String appName)

contextInitialized

public void contextInitialized(javax.servlet.ServletContextEvent sce)
Basic implementation of the web application cleanup upon context creation. If this method is subclassed, the subclassed method must also invoke this method via super.contextInitialized. This call should typically be at the beginning of the subclassed method, which allows this implementation to create connections, logs etc, which can then be used by the subclass to finish it's further initialization as needed.

Specified by:
contextInitialized in interface javax.servlet.ServletContextListener

contextDestroyed

public void contextDestroyed(javax.servlet.ServletContextEvent sce)
Basic implementation of the web application cleanup upon context destruction. If this method is subclassed, the subclassed method must also invoke this method via super.contextInitialized. This invokation should typically be at the end of the subclassed method (which allows the subclass to use connections etc., before they are closed by this superclass method).

Specified by:
contextDestroyed in interface javax.servlet.ServletContextListener

addWebApp

public static WebApp addWebApp(javax.servlet.ServletContext context,
                               String appName,
                               String sconf)
Add a new WebApp instance manually. A WebApp is typically specified as a context listener, in a particular web.xml, and configures itself as representing that context wide configuration (common to all servlets and pages running inside that context). There is only 1 instance of the WebApp class that is instantiated per context by the servlet container.

However, for REST services and other API's, it is useful to have several API versions, such as /rest/v1/, /rest/v2/, etc., all of which are tied to seperate servlets in the same webapp. We could also create separate webapps inside separate folders, such as /w3root/rest/v1, /w3root/rest/v2, each of which would have their own web.xml (and hence separate configuration).

However, we sometimes need to access a particular REST api's classes directly from the "root" document webapp (which is running molly pages, etc). If the REST api's are in separate contexts, the root webapp (a different webapp from all the other REST api versioned webapps) cannot access those api classes directly. This becomes a hassle if we want to use our API directly to show results on a molly web page.

So we use only one webapp, with separate servlets in that webapp. Example: RESTServletV1, RESTServletV2, etc., to handle and serve different version of the API.

So then, each of these servlets have to be configured as well with connection pools, loggers, etc, each of them specific to a particular servlet/api. This can be done via servlet init parameters, but since the whole point of WebApp is to set up this configuration easily, it is also useful to create a WebApp instance per servlet instance in the same webapp.

Servlets can then call this method with different appNames (unique to each servlet) and different configuration files (again unique to each servlet). When the context is destroyed, all these manually added webapps will also be automatically closed.

This class must be specified as a listener in web.xml (even if the context wide config file has no configuration data, use an empty config file in that case).

PS: If this makes your head hurt, you are in good company. My head hurts too.

Parameters:
context - the servlet context the calling servlet is running in
appName - the name of the WebApp to associate with the calling servlet
conf - the configuration file for the WebApp

getPropertyMgr

public PropertyMgr getPropertyMgr()
Returns the property manager associated with this WebApp (properties of the app configuration file can be read via this property mgr)


getConnectionMgr

public ConnectionMgr getConnectionMgr(String databasename)
Returns the connection manager corresponding to the database name. (specified in the dblist property of app.conf).

Throws:
IllegalArgumentException - if the specified database is not found

getConnectionMgr

public ConnectionMgr getConnectionMgr()
Returns the connection manager corresponding to the default database name. (specified in the dbdefault property of app.conf). Returns null if no default database has been initialized.


getConnection

public Connection getConnection(String databasename)
                         throws SQLException
Throws:
SQLException

getConnection

public Connection getConnection()
                         throws SQLException
Throws:
SQLException

getAppLog

public Log getAppLog()

getForm

public Form getForm(String name)
Convenience method to return a form stored previously via the putForm method. Returns null if no form with the specified name was found.


putForm

public void putForm(Form f)

removeForm

public void removeForm(String name)

getDBCache

public Cache getDBCache()
Convenience method to get the pre-created application cache. This can be used for caching database results as necessary. Each entry in the cache can be stored for entry-specific time-to-live (see {@link Cache) but if no entry-specific-time-to-live is specified, then entries are cached for a default time of 5 minutes. Of course, cached entries should always be invalidated sooner whenever the database is modified.


getThreadLocalDateFormat

public ThreadLocalDateFormat getThreadLocalDateFormat(String name)
Returns the ThreadLocalDateFormat object corresponding to the specified name (a new ThreadLocalDateFormat is created if it does not exist).


getThreadLocalDateFormat

public ThreadLocalDateFormat getThreadLocalDateFormat()
Returns the default threadLocalDateFormat object (a new ThreadLocalDateFormat is created if it does not exist).


getThreadLocalNumberFormat

public ThreadLocalNumberFormat getThreadLocalNumberFormat(String name)
Returns the ThreadLocalNumberFormat object corresponding to the specified name (a new ThreadLocalNumberFormat is created if it does not exist).


getThreadLocalNumberFormat

public ThreadLocalNumberFormat getThreadLocalNumberFormat()
Returns the default ThreadLocalNumberFormat object (a new ThreadLocalNumberFormat is created if it does not exist).


getThreadLocalCalendar

public ThreadLocalCalendar getThreadLocalCalendar(String name)
Returns the ThreadLocalCalendar object corresponding to the specified name (a new ThreadLocalCalendar is created if it does not exist).


getThreadLocalCalendar

public ThreadLocalCalendar getThreadLocalCalendar()
Returns the default ThreadLocalCalendar object (a new ThreadLocalCalendar is created if it does not exist).


getThreadLocalRandom

public ThreadLocalRandom getThreadLocalRandom(String name)
Returns the ThreadLocalRandom object corresponding to the specified name (a new ThreadLocalRandom is created if it does not exist).


getThreadLocalRandom

public ThreadLocalRandom getThreadLocalRandom()
Returns the default ThreadLocalRandom object (a new ThreadLocalRandom is created if it does not exist).


getThreadLocalObject

public ThreadLocalObject getThreadLocalObject(String name)
Returns the ThreadLocalObject corresponding to the specified name (a new ThreadLocalObject is created if it does not exist).


get

public Object get(Object key)
Returns the specified object from the global application map or null if the object was not found.


put

public void put(Object key,
                Object val)
Puts the specified key/object into the global application map.


toString

public String toString()
Overrides:
toString in class Object