Qwicap Deployment Descriptors

Contents

• Quick Start
• Introduction
• Default "web.xml" File for Qwicap 1.4 Applications
  • Customizable Items
• Manually Specifying an Application's Entry Point
• Specifying Multiple Servlets

Quick Start

If all you need is a "web.xml" file that will make your Qwicap web application work, skip down to the default file shown below, and use it. No modifications should be required. If you want an understanding of the web application deployment descriptor, or Qwicap's automatic entry point detection feature, read on.

Introduction

Qwicap is based on Java Servlets, and provides a servlet class that manages all Qwicap-based web applications. Those applications are not, themselves, servlets; they are classes loaded and invoked by Qwicap's own servlet class. In order for Qwicap's servlet to load and execute your application's main class, it must be able to determine the identity of that class.

Beginning with version 1.4, Qwicap will automatically scan all of your application's classes in search of one that has a "public static void main(String[])" method, and which also references the class "edu.utexas.its.eis.tools.qwicap.servlet.Qwicap". A class meeting those criteria is considered to be the entry point of your web application. Qwicap will begin its search for the entry point by scanning all of the classes in your application's "WEB-INF/classes" directory hierarchy. If that fails, it will scan all of the classes in the JAR files located in your application's "WEB-INF/lib" directory. Either scan will fail if no entry point is found, or if more than one entry point is located. If either scan is successful in locating your application's entry point, Qwicap will begin the execution of your application. If not, it will throw an explanatory exception.

That automatic entry point detection feature usually allows developers to use the default web application deployment descriptor ("web.xml" file) shown below in all of their Qwicap web applications, without modification. Using that default deployment descriptor, a web application is accessed with a URL specifying the host, the optional port, and the name of the web application, for example: "http://localhost:8080/mywebapp".

Default "web.xml" File for Qwicap 1.4 Applications

<?xml version="1.0" encoding="UTF-8"?>    

<!DOCTYPE web-app 
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd"> 

<web-app>

    <display-name>Qwicap Web Application</display-name>
    <description>
        A web application built on the Quick Web Interface for Conventional 
        Applications (QWICAP), using Qwicap's default, general-purpose 
        "web.xml" file.
    </description>

    <context-param>
        <param-name>qwicap-development-mode</param-name>
        <param-value>false</param-value>
        <description>
            If this value is "true", when reporting an exception Qwicap
            includes the error message from the exception in the user-
            visible message that it displays, and it also embeds into a 
            comment block in the web page the entire chain of stack 
            traces from the exception. This can be useful during the 
            development and debugging of a web application, but is a bad 
            practice from a security standpoint.
            
            If this value is "false", Qwicap only reports opaque "incident
            codes" to the user, and never includes stack traces in the 
            pages. This gives would-be attackers vastly less information 
            with which to guide their attacks.
            
            If this context parameter is omitted, development mode is 
            considered to be disabled.
        </description>
    </context-param>
    
    <context-param>
        <param-name>qwicap-threads-minimum</param-name>
        <param-value>0</param-value>
        <description>
            The number of threads initially present in Qwicap's thread 
            pool. This value must not be greater than 
            "qwicap-threads-spare-maximum".
        </description>
    </context-param>
    
    <context-param>
        <param-name>qwicap-threads-spare-maximum</param-name>
        <param-value>0</param-value>
        <description>
            The maximum number of spare threads that Qwicap will retain 
            in its thread pool. This value must not be greater than 
            "qwicap-threads-maximum".
        </description>
    </context-param>
    
    <context-param>
        <param-name>qwicap-threads-maximum</param-name>
        <param-value>1000</param-value>
        <description>
            The maximum size of the Qwicap thread pool. This is the 
            maximum number of concurrent users this web application 
            will be able to support.
        </description>
    </context-param>
    
    <context-param>
        <param-name>qwicap-thread-stack-kilobytes</param-name>
        <param-value>0</param-value>
        <description>
            The amount of stack space allocated to each thread in the 
            thread pool. A value of zero causes the platform-specific 
            default stack size to be used. Platforms are free to 
            ignore, or change, the stack size setting, no matter what 
            value is specified.
        </description>
    </context-param>
    
    <servlet>
        <servlet-name>QwicapDefault</servlet-name>
        <display-name>Qwicap Web Application Component</display-name>
        <description>
            A web application component built on the Quick Web Interface for 
            Conventional Applications (QWICAP).
        </description>
        <servlet-class>edu.utexas.its.eis.tools.qwicap.servlet.QwicapServlet</servlet-class>
    </servlet>
    
    <servlet-mapping>
        <servlet-name>QwicapDefault</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>
    
    <session-config>
        <session-timeout>10</session-timeout>    <!-- 10 minutes -->
    </session-config>
    
</web-app>

Customizable Items

• <session-timeout> tag - Sets the number of minutes a user's session is allowed to be inactive before it is classified as abandoned and is automatically torn-down. Because Qwicap allocates a thread to every user's session, timely culling of abandoned sessions can be important.

• qwicap-development-mode context parameter - If this value is "true", when reporting an exception Qwicap includes the error message from the exception in the user-visible message that it displays, and it also embeds into a comment block in the web page the entire chain of stack traces from the exception. This behavior simplifies development and debugging by giving developers easy, immediate access to all of the information about each exception they encounter, directly in the page (and page source), so there's no need for them to go through the server's log files in order to find that information.

  Unfortunately, that behavior represents a serious security hole, because the messages and strack traces from exceptions can give attackers a lot of information, including the manner in which their attack attempts are penetrating an application. With such information, they can potentially alter their attack methods to steer their attacks into more vulnerable/important areas of the application's code, or they can tailor their attacks to the type of code that is throwing the exceptions. For example, if you know that your attacks are reaching code associated with the database, concentrating your efforts on things like SQL injection attacks would make sense.

  To deny attackers that helpful information, set the value of this context parameter to "false", which is also the default value when this context parameter is absent. With the value set to "false", Qwicap only reports opaque "incident codes" to users – no information of any kind from an exception is ever included in any web page. The incident codes, which consist of the day's date and a random number (for example "20080131-A079C2"), provide users with a concise way of reporting the errors they encounter, and make it straightforward for the developer to find the relevant exception report in the server's logs.

• qwicap-threads-minimum context parameter - Sets the initial number of threads Qwicap will create to represent user's sessions. Qwicap will automatically create new threads as necessary (up to the limit established by "qwicap-threads-maximum"), so this parameter isn't very useful unless you want to force Qwicap to pre-allocate the maximum number of threads. (If this parameter is omitted, a default value of 10 is used.)
• qwicap-threads-spare-maximum context parameter - Sets the maximum number of spare threads that Qwicap will retain. Put another way, this is the upper limit on the number of extra threads that Qwicap will hold onto in its thread pool, on the presumption that they will be used again some time in the future. (If this parameter is omitted, a default value of 20 is used.)

• qwicap-threads-maximum context parameter - Sets the maximum number of threads this Qwicap web application will create to represent users' sessions. Put another way, this is the upper limit on the number of concurrent users of your web application. (If this parameter is omitted, a default value of 100 is used.)

  In cases where the maximum number of concurrent users of a Qwicap web application is not predictable, it is generally best to keep this value at least as large as the relevant web application server's maximum thread limit, and the number of waiting connections the server will accept should also be at least as large as, but probably double, the application server's maximum thread limit.

  For instance, in the case of Tomcat, this means that the relevant "Connector" elements in Tomcat's "server.xml" file should have the value of their "acceptCount" attributes set to at least 1-2 times the value of their "maxThreads" attributes ("acceptCount" is, in effect, the total number of hits you are willing to allow a connector to accept concurrently), and the value of the "maxThreads" attribute should be a value somewhat in excess of the number of hits that you want to attempt to process concurrently. Since each of those threads needs a correspondng Qwicap thread to maintain a user's session, the value of the "qwicap-threads-maximum" context parameter should be set at least as high as the sum of the relevant "Connector" elements' "maxThreads" attribute values. "At least as high" is recommended, because the number of concurrent users is likely to be larger than the number of concurrent hits being accepted or processed.

• qwicap-thread-pool-stack-kilobytes context parameter - Recommends the size of the stack, in kilobytes (KB), that should allocated for each thread in Qwicap's thread pool. (Be aware that the underlying platform may ignore, or alter, this recommendation.) Zero is the default value, and will cause the local platform to use a reasonable default. If you choose to customize this value, bear in mind that the appropriate value will vary not only due to the way your application uses stack space, and the manner in which it is used by the user, but due to the particulars of the underlying platform, as well. Using too small a value can crash Tomcat, or, in less extreme situations, result in StackOverflowErrors being thrown. On the other hand, using too large a value will merely waste some memory. So, using a stack size value other than zero should be done with care, and as a server-specific optimization. In general, web applications should ship with the stack size set to zero, as shown above in the default "web.xml" file. (If this parameter is omitted, a default value of 0 is used.)

Manually Specifying an Application's Entry Point

In situations where Qwicap's automatic entry point detection feature is inadequate to your needs, the entry point can be specified manually by adding an "init-param" tag inside the "servlet" tag, as illustrated below. The content of the "param-value" tag should be the fully-qualified name of the class in your application that contains the "public static void main(String[])" method at which the execution of your web application should begin.

    <servlet>
        <servlet-name>QwicapDefault</servlet-name>
        <display-name>Qwicap Web Application Component</display-name>
        <description>
            A web application component built on the Quick Web Interface for 
            Conventional Applications (QWICAP).
        </description>
        <servlet-class>edu.utexas.its.eis.tools.qwicap.servlet.QwicapServlet</servlet-class>
        <init-param>
            <param-name>QwicapClientClassName</param-name>
            <param-value>com.mycompany.myproject.MyMainClass</param-value>
            <description>Manually specified application entry point.</description>
        </init-param>
    </servlet>

Specifying Multiple Servlets

Web application deployment descriptors are allowed to include multiple "servlet" tags. Qwicap 1.4, however, supports only a single servlet in each web application. Specifying more than one servlet will produce undefined, but assuredly bad, results. So, don't do that. Support for multiple servlets (for Qwicap's purposes, that's effectively the same as combining several different web applications in one) may be restored in the future.