com.primix.tapestry
Class ApplicationServlet

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--com.primix.tapestry.ApplicationServlet
All Implemented Interfaces:
java.io.Serializable, Servlet, ServletConfig
Direct Known Subclasses:
AdderServlet, BorderServlet, HangmanServlet, HelloWorldServlet, LocaleServlet, PortalServlet, SimpleServlet, SurveyServlet, ValidServlet, VirtualLibraryServlet

public abstract class ApplicationServlet
extends HttpServlet

Links a servlet container with a Tapestry application. The servlet has some responsibilities related to bootstrapping the application (in terms of logging, reading the specification, etc.). It is also responsible for creating or locating the IEngine and delegating incoming requests to it.

In some servlet containers (notably WebLogic) it is necessary to invoke HttpSession.setAttribute(String,Object) in order to force a persistent value to be replicated to the other servers in the cluster. Tapestry applications usually only have a single persistent value, the engine. For persistence to work in such an environment, the JVM system property com.primix.tapestry.store-engine must be set to true. This will force the application servlet to restore the engine into the HttpSession at the end of each request cycle.

The application servlet also has a default implementation of setupLogging() that configures logging for Log4J. Subclasses with more sophisticated logging needs will need to overide this method.

As of release 1.0.1, it is no longer necessary for a HttpSession to be created on the first request cycle. Instead, the HttpSession is created as needed by the IEngine ... that is, when a visit object is created, or when persistent page state is required. Otherwise, for sessionless requests, an IEngine from a Pool is used. Additional work must be done so that the IEngine can change locale without forcing the creation of a session; this involves the servlet and the engine storing locale information in a Cookie.

This class is derived from the original class com.primix.servlet.GatewayServlet, part of the ServletUtils framework available from The Giant Java Tree.

Version:
$Id: ApplicationServlet.java,v 1.22 2001/09/10 18:25:14 hship Exp $
Author:
Howard Ship
See Also:
Serialized Form

Constructor Summary
ApplicationServlet()
           
 
Method Summary
protected  IEngine createEngine(RequestContext context)
          Invoked by getEngine(RequestContext) to create the IEngine instance specific to the application, if not already in the HttpSession.
 void doGet(HttpServletRequest request, HttpServletResponse response)
          Invokes doService(HttpServletRequest, HttpServletResponse).
 void doPost(HttpServletRequest request, HttpServletResponse response)
          Invokes doService(HttpServletRequest, HttpServletResponse).
protected  void doService(HttpServletRequest request, HttpServletResponse response)
          Handles the GET and POST requests.
 ApplicationSpecification getApplicationSpecification()
          Returns the application specification, which is read by the init(ServletConfig) method.
protected abstract  java.lang.String getApplicationSpecificationPath()
          Implemented in subclasses to identify the resource path of the application specification.
protected  IEngine getEngine(RequestContext context)
          Retrieves the engine that will process this request.
protected  java.util.Locale getLocaleFromRequest(RequestContext context)
          Determines the Locale for the incoming request.
 void init(ServletConfig config)
          Reads the application specification when the servlet is first initialized.
protected  void setupLogging()
          Invoked from init(ServletConfig) before the specification is loaded to setup log4j logging.
protected  void show(java.lang.Exception ex)
           
 void writeLocaleCookie(java.util.Locale locale, IEngine engine, RequestContext cycle)
          Invoked from the engine, just prior to starting to render a response, when the locale has changed.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ApplicationServlet

public ApplicationServlet()
Method Detail

doGet

public void doGet(HttpServletRequest request,
                  HttpServletResponse response)
           throws java.io.IOException,
                  ServletException
Invokes doService(HttpServletRequest, HttpServletResponse).
Overrides:
doGet in class HttpServlet
Since:
1.0.6

doService

protected void doService(HttpServletRequest request,
                         HttpServletResponse response)
                  throws java.io.IOException,
                         ServletException
Handles the GET and POST requests. Performs the following:

show

protected void show(java.lang.Exception ex)

doPost

public void doPost(HttpServletRequest request,
                   HttpServletResponse response)
            throws java.io.IOException,
                   ServletException
Invokes doService(HttpServletRequest, HttpServletResponse).
Overrides:
doPost in class HttpServlet

getApplicationSpecification

public ApplicationSpecification getApplicationSpecification()
Returns the application specification, which is read by the init(ServletConfig) method.

getEngine

protected IEngine getEngine(RequestContext context)
                     throws ServletException
Retrieves the engine that will process this request. This comes from one of the following places:

getLocaleFromRequest

protected java.util.Locale getLocaleFromRequest(RequestContext context)
                                         throws ServletException
Determines the Locale for the incoming request. This is determined from the locale cookie or, if not set, from the request itself. This may return null if no locale is determined.

init

public void init(ServletConfig config)
          throws ServletException
Reads the application specification when the servlet is first initialized. All engine instances will have access to the specification via the servlet.
Overrides:
init in class GenericServlet

setupLogging

protected void setupLogging()
                     throws ServletException
Invoked from init(ServletConfig) before the specification is loaded to setup log4j logging. This implemention is sufficient for testing, but should be overiden in production applications.

In addition, for each priority, a check is made for a JVM system property com.primix.tapestry.log4j.priority (i.e. ...log4j.DEBUG). The value is a list of categories seperated by semicolons. Each of these categories will be assigned that priority.

Since:
0.2.9

getApplicationSpecificationPath

protected abstract java.lang.String getApplicationSpecificationPath()
Implemented in subclasses to identify the resource path of the application specification.

createEngine

protected IEngine createEngine(RequestContext context)
                        throws ServletException
Invoked by getEngine(RequestContext) to create the IEngine instance specific to the application, if not already in the HttpSession.

The IEngine instance returned is stored into the HttpSession.

This implementation instantiates a new engine as specified by ApplicationSpecification.getEngineClassName().


writeLocaleCookie

public void writeLocaleCookie(java.util.Locale locale,
                              IEngine engine,
                              RequestContext cycle)
Invoked from the engine, just prior to starting to render a response, when the locale has changed. The servlet writes a Cookie so that, on subsequent request cycles, an engine localized to the selected locale is chosen.

At this time, the cookie is not persistent. That may change in subsequent releases.

Since:
1.0.1