hirondelle.web4j
Class Controller

Object
  GenericServlet
      HttpServlet
          hirondelle.web4j.Controller

All Implemented Interfaces:

Serializable, Servlet, ServletConfig

public class Controller
extends HttpServlet

Single point of entry for serving dynamic pages.

The application can serve content both directly (by simple, direct reference to a JSP's URL), and indirectly, through this Controller.

Like almost all servlets, this class is safe for multi-threaded environments.

Validates user input and request parameters, interacts with a datastore, and places problem domain model objects in scope for eventual rendering by a JSP. Performs either a forward or a redirect, according to the instructions of the Action.

Emails are sent to the webmaster when :

• an unexpected problem occurs (the email will include extensive diagnostic information, including a stack trace)
• servlet response times degrade to below a configured level

This class is in a distinct package for two reasons :

• to make it easier to find, since it is at the very top of the hierarchy
• to force the Controller to use only the public aspects of the ui package. This ensures it remains at a high level of abstraction.

There are key-names defined in this class (see below). Their names need to be long-winded (web4j_key_for_...), unfortunately, in order to avoid conflict with other tools, including your application.

See Also:

Serialized Form

Field Summary

static String	CHARACTER_ENCODING Key name for the application's character encoding, placed in application scope as a String upon startup.
static String	CURRENT_URI Key name for the URI for the current request, placed in request scope as a String.
static String	LOCALE Key name for the default Locale, placed in application scope as a Locale upon startup.
static String	MOST_RECENT_TROUBLE_TICKET Key name for the most recent TroubleTicket, placed in application scope when a problem occurs.
static String	START_TIME Key name for the startup time, placed in application scope as a DateTime upon startup.
static String	TIME_ZONE Key name for the default TimeZone, placed in application scope as a TimeZone upon startup.
static String	WEB4J_VERSION Name and version number of the WEB4J API.
static String	WEBMASTER Key name for the webmaster email address, placed in application scope as a String upon startup.

Constructor Summary

Controller()

Method Summary

void	destroy() Log the name and version of the application.
void	doDelete(HttpServletRequest aRequest, HttpServletResponse aResponse) Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse).
void	doGet(HttpServletRequest aRequest, HttpServletResponse aResponse) Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse).
void	doPost(HttpServletRequest aRequest, HttpServletResponse aResponse) Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse).
void	doPut(HttpServletRequest aRequest, HttpServletResponse aResponse) Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse).
void	init(ServletConfig aConfig) Perform operations to be executed only upon startup of this application, and not during its regular operation.
protected void	logAndEmailPerformanceProblem(String aMilliseconds, HttpServletRequest aRequest) Inform the webmaster of a performance problem.
protected void	logAndEmailSeriousProblem(Throwable aException, HttpServletRequest aRequest) Inform the webmaster of an unexpected problem with the deployed application.
protected void	processRequest(HttpServletRequest aRequest, HttpServletResponse aResponse) Handle all HTTP requests for GET, POST, PUT, and DELETE requests.
protected ResponsePage	swapResponsePage(ResponsePage aResponsePage, Locale aLocale) Change the ResponsePage according to Locale.

Methods inherited from class HttpServlet

doHead, doOptions, doTrace, getLastModified, service, service

Methods inherited from class GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class Object

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

Field Detail

WEB4J_VERSION

public static final String WEB4J_VERSION

Name and version number of the WEB4J API.

Value: "WEB4J/4.10.0".

Upon startup, this item is logged at CONFIG level. (This item is is simply a hard-coded field in this class. It is not configured in web.xml.)

See Also:

Constant Field Values

CHARACTER_ENCODING

public static final String CHARACTER_ENCODING

Key name for the application's character encoding, placed in application scope as a String upon startup. This character encoding (charset) is set as an HTTP header for every reponse.

Key name: "web4j_key_for_character_encoding".

Configured in web.xml. The value UTF-8 is highly recommended.

See Also:

Constant Field Values

WEBMASTER

public static final String WEBMASTER

Key name for the webmaster email address, placed in application scope as a String upon startup.

Key name: "web4j_key_for_webmaster".

Configured in web.xml.

See Also:

Constant Field Values

LOCALE

public static final String LOCALE

Key name for the default Locale, placed in application scope as a Locale upon startup.

Key name: "web4j_key_for_locale".

The application programmer is encouraged to use this key for any Locale stored in session scope : the default implementation of LocaleSource will always search for this key in increasingly larges scopes. Thus, the default mechanism will automatically use the user-specific Locale as an override to the default one.

Configured in web.xml.

See Also:

Constant Field Values

TIME_ZONE

public static final String TIME_ZONE

Key name for the default TimeZone, placed in application scope as a TimeZone upon startup.

Key name: "web4j_key_for_time_zone".

The application programmer is encouraged to use this key for any TimeZone stored in session scope : the default implementation of TimeZoneSource will always search for this key in increasingly larges scopes. Thus, the default mechanism will automatically use the user-specific TimeZone as an override to the default one.

Configured in web.xml.

See Also:

Constant Field Values

MOST_RECENT_TROUBLE_TICKET

public static final String MOST_RECENT_TROUBLE_TICKET

Key name for the most recent TroubleTicket, placed in application scope when a problem occurs.

Key name: "web4j_key_for_most_recent_trouble_ticket".

See Also:

Constant Field Values

START_TIME

public static final String START_TIME

Key name for the startup time, placed in application scope as a DateTime upon startup.

Key name: "web4j_key_for_start_time".

See Also:

Constant Field Values

CURRENT_URI

public static final String CURRENT_URI

Key name for the URI for the current request, placed in request scope as a String.

Key name: "web4j_key_for_current_uri".

Somewhat bizarrely, the servlet API does not allow direct access to this item.

See Also:

Constant Field Values

Constructor Detail

Controller

public Controller()

Method Detail

init

public final void init(ServletConfig aConfig)
                throws ServletException

Perform operations to be executed only upon startup of this application, and not during its regular operation.

Operations include :

• log version and configuration information
• distribute configuration information in web.xml to the various parts of WEB4J
• place an ApplicationInfo object into application scope
• place the configured character encoding into application scope, for use in JSPs
• call StartupTasks.startApplication(ServletConfig, String), to allow the application to perform its own startup tasks
• perform various validations

One or more of the application's databases may not be running when the web application starts. Upon startup, this Controller first queries each database for simple name and version information. If that query fails, then the database is assumed to be "down", and the app's implementation of StartupTasks (which usually fetches code tables from the database) is not called.

The web app, however, will not terminate. Instead, this Controller will keep attempting to connect for each incoming request. When all databases are determined to be healthy, the Controller will perform the database initialization tasks it usually performs upon startup, and the app will then function normally.

If the database subsequently goes down again, then this Controller will not take any special action. Instead, the container's connection pool should be configured to attempt to reconnect automatically on the application's behalf.

Specified by:

init in interface Servlet

Overrides:

init in class GenericServlet

Throws:

ServletException

destroy

public void destroy()

Log the name and version of the application.

Specified by:

destroy in interface Servlet

Overrides:

destroy in class GenericServlet

doGet

public final void doGet(HttpServletRequest aRequest,
                        HttpServletResponse aResponse)
                 throws IOException

Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse).

Overrides:

doGet in class HttpServlet

Throws:

IOException

doPost

public final void doPost(HttpServletRequest aRequest,
                         HttpServletResponse aResponse)
                  throws IOException

Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse).

Overrides:

doPost in class HttpServlet

Throws:

IOException

doPut

public final void doPut(HttpServletRequest aRequest,
                        HttpServletResponse aResponse)
                 throws IOException

Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse). PUT can be called by XmlHttpRequest.

Overrides:

doPut in class HttpServlet

Throws:

IOException

doDelete

public final void doDelete(HttpServletRequest aRequest,
                           HttpServletResponse aResponse)
                    throws IOException

Call processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse). DELETE can be called by XmlHttpRequest.

Overrides:

doDelete in class HttpServlet

Throws:

IOException

processRequest

protected void processRequest(HttpServletRequest aRequest,
                              HttpServletResponse aResponse)
                       throws IOException

Handle all HTTP requests for GET, POST, PUT, and DELETE requests. All of these HTTP methods will funnel through this Java method; any other methods will be handled by the container. If a subclass needs to know the underlying HTTP method, then it must call HttpServletRequest.getMethod().

This method can be overridden, if desired. The great majority of applications will not need to override this method.

Operations include :

• set the request character encoding (using the value configured in web.xml)
• set the charset HTTP header for the response (using the value configured in web.xml)
• react to a successful user login, using the configured implementation of LoginTasks
• get an instance of RequestParser
• get its Action, and execute it
• check for an ownership constraint (see UntrustedProxyForUserId)
• perform either a forward or a redirect to the Action's ResponsePage
• if an unexpected problem occurs, create a TroubleTicket, log it, and email it to the webmaster email address configured in web.xml
• if the response time exceeds a configured threshold, build a TroubleTicket, log it, and email it to the webmaster address configured in web.xml

Throws:

IOException

swapResponsePage

protected ResponsePage swapResponsePage(ResponsePage aResponsePage,
                                        Locale aLocale)

Change the ResponsePage according to Locale.

This overridable default implementation does nothing, and returns null. If the return value of this method is null, then the nominal ResponsePage will be used without alteration. If the return value of this method is not null, then it will be used to override the nominal ResponsePage.

This method is intended for applications that use different JSPs for different Locales. For example, if the nominal response is a forward to Blah_en.jsp, and the "real" response should be Blah_fr.jsp, then this method can be overridden to return the appropriate ResponsePage. This method is called only for forward operations. If it is overridden, then its return value must also correspond to a forward operation.

This style of implementing translation is not recommended. Instead, please use the services of the hirondelle.web4j.ui.translate package.

logAndEmailSeriousProblem

protected final void logAndEmailSeriousProblem(Throwable aException,
                                               HttpServletRequest aRequest)

Inform the webmaster of an unexpected problem with the deployed application.

Typically called when an unexpected Exception occurs in processRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse). Uses TroubleTicket.mailToRecipients().

Also, stores the trouble ticket in application scope, for possible later examination.

logAndEmailPerformanceProblem

protected final void logAndEmailPerformanceProblem(String aMilliseconds,
                                                   HttpServletRequest aRequest)

Inform the webmaster of a performance problem.

Called only when the response time of a request is above the threshold value configured in web.xml.

Builds a Throwable with a description of the problem, then creates and emails a TroubleTicket to the webmaster.

Parameters:

aMilliseconds - response time of a request in milliseconds