Creating a `web.xml` file at build time

Because web.xml files are single system, and duplicate a lot of information that is embedded inside the Java source itself, many people have set up build processes that dynamically create web.xml files.

There are a number of tools that can do this, all under Ant and sometimes Maven.

xdoclet
Apache Velocity
Ant <copy> with property expansion
Patching an existing WAR file.

For dynamically generating a single web.xml file for all target systems, xdoclet was historically a good solution. It could extract information from javadoc source markup and build a list of servlets. Other content could be merged in, with Ant properties dynamically turning specific servlets on or off (such as debug entry points), or filling in system configuration constants.

However, it is effectively dead. There have been no recent releases from the XDoclet 2 site, and the XDoclet 1 release does not work with Java 5 source code. This is a shame as there is not yet any mainstream alternative, such as official Java 5 attributes for declaring web.xml values such as servlet mappings.

When creating web.xml files for different target uses, such as different installations, including test systems with diagnostic/test servlets enabled, it is imperative to generate differently named artifacts. Naming one war file system-production.war should differentiate it from system-test.war and system-client7.war. However, doing so creates problems downstream, as the name of the WAR file is used by the application servers to determine the base of all URLs. One workaround is to keep the same .war name, but package the war into differently named systems -either a different .zip file (which forces an unzip before deployment), or by embedding it inside an .ear file. The unzipping of this is handled by the runtime -but you are then restricted to deploying to application servers.

Warning
If you do not somehow give test and production war files different names, at some point in the future, the test WAR will be deployed to the production system. This is inevitable.

For simple Ant property expansion of a single web.xml file, with the resulting WAR file shared across all installations, this technique is simple and reliable.

Features

Build time construction of web.xml files from properties and source

Advantages

Allows web.xml configurations to be parameterized.
Can eliminate duplication between source and web.xml.
Allows for custom web.xml files for different target systems.
All configuration state is kept under SCM.

Disadvantages

Requires a rebuild to change configuration options.
Target-specific WAR files need to be built for every target deployment.
Strong risk of accidental deployment of a specific WAR instance to the wrong target.
The best tool for this process - XDoclet - is no longer being maintained.
Ant property expansion requires Ant to be used in the build; can complicate IDE integration.

If you are going to do this, you need to generate WAR files with different names for different target systems, otherwise the wrong WAR file will be deployed on the wrong system. Unfortunately, renaming a WAR file means the application gets a different name -the root of the application is implicitly determined from the filename. A workaround here is to leave the name the same, but package up the war inside another ZIP file, a file which is named for the specific target. Deployment is no longer Pattern - Deploy by Copy, but [Deploy by Unzip].

SmartFrog support

This is not something which SmartFrog supports; it is the area of build tools. SmartFrog prefers run-time configuration of applications. We do use this technique in part of our release process, generating RPM and IZPack installers that are up to date with the specific versions of all the Java libraries which we distribute. That said, we have velocity support; generating a web.xml through a velocity template is fairly simple.

Ant support

First, you need to define a <presetdef> task that expands properties in a copy

   <presetdef name="expandingcopy">
     <copy overwrite="true">
       <filterchain>
         <expandproperties/>
       </filterchain>
     </copy>
   </presetdef>

Then you add Ant property declarations into the file itself.

  <welcome-file-list id="WelcomeFileList">
    <welcome-file>${web.xml.welcome.files}</welcome-file>
  </welcome-file-list>

This template file is then turned into the life file by setting the property and then copying it.

  <property name="web.xml.welcome.files" value="index.html,index.jsp" />
  <expandingcopy todir="${build.dir}/web/">
    <fileset dir="web" includes="WEB-INF/*.xml"/>
  </expandingcopy>

Although this may seem pointless, it is possible to override that specific definition with a new value, such as from a build.properties file or a command line option:

ant clean release -Dweb.xml.welcome.files=index.html

Build-Time Web xml file