The Web Application Deployment Descriptor: web.xml

Java Web Applications are configured through the file WEB-INF/web.xml, inside the WAR archive. The format of this web.xml file is described in the servlet specifications. It is an XML file that lists all servlets to be deployed, what mime mappings to support, an ordered list of index pages to automatically return, and any custom configuration options to make visible through the ServletConfig
and ServletContext.

Here's a simple example; the web.xml file from SmartFrog's internal test web application; an application used to test deployment on all supported application servers.

<?xml version="1.0" encoding="ISO-8859-1"?>

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

<web-app>
  <display-name>Testwar</display-name>

  <servlet>
    <servlet-name>HappyServlet</servlet-name>
    <display-name>Happy Servlet</display-name>
    <servlet-class>
      org.smartfrog.test.testwar.HappyServlet
    </servlet-class>
  </servlet>
  <servlet>
    <servlet-name>ErrorServlet</servlet-name>
    <display-name>Error Servlet</display-name>
    <servlet-class>
      org.smartfrog.test.testwar.ErrorCodeServlet
    </servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>HappyServlet</servlet-name>
    <url-pattern>/happy</url-pattern>
  </servlet-mapping>

  <servlet-mapping>
    <servlet-name>ErrorServlet</servlet-name>
    <url-pattern>/error</url-pattern>
  </servlet-mapping>

  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.jsp</welcome-file>
  </welcome-file-list>
</web-app>

Features

• well-known XML format for system configuration
• included in the WAR file when it is built, and hence bundled into the application.
• historically, it was illegal to deploy a web application without a web.xml file; this rule has recently been relaxed in Servlet 2.5+ runtimes.

Advantages

• Many IDEs are aware of the format, and have custom tools to aid in writing a correct web.xml file.
• Pulls all server configuration data into one single place.
• Can be kept under SCM.
• Standard API for reading this (static) configuration information.

Disadvantages

• Historically, very brittle regarding the correct ordering of declarations
• All information has to be manually entered, even when much of it is included in the java source itself
• No way to provide custom configurations for different installations, other than through build-time generation of new web.xml and WAR files for the different targets.
• Some declarations are white-space sensitive; if you lay out the text for readability, white-space that is inserted can affect the configuration.

SmartFrog support

We've got no explicit support for dynamically generating web.xml files at deployment time although it is something we have considered. Certainly the sf-xml components can be used to generate a web.xml file, but ideally the sf-www components would contain support for building a web.xml file from declared information. Why? So that we can pass configuration information from the rest of the deployment into the web.xml file.

The sf-www components do have a ServletContext component that can replace the web.xml descriptor; it is supported in Jetty through theThe sf-jetty components. It allows servlets to be defined in one descriptor

AlpineServlet extends Servlet {
    name "alpine";
    contextPath "/alpine";
    className "org.smartfrog.projects.alpine.http.SoapPostServlet";
}

This servlet can be deployed into a servlet context, a context that also supports mime mappings and other web.xml options.

    servlets extends ServletContext {
        resourceBase LAZY tempdir;
        contextPath "/";
        server LAZY jettyServer;

     }

      alpine extends AlpineServletOnJetty {
         pathSpec "/alpine/*";
         initOrder 5;
         context LAZY servlets;
      }

This is supported in Jetty as it offers a stable API for configuring the servlet engine. For other application servers, it would be simpler to generate a new web.xml file that was added to the classpath (perhaps a new WAR file would be created). Watch/contribute to SFOS-609.