2011/08/05 - Jakarta Cactus has been retired.

For more information, please explore the Attic.

WebXmlMerge Task

The task webxmlmerge provides a convenient way to inject external definitions into a web deployment descriptor (web.xml) from an Ant build. It's primary intended use is to include the definition of the Cactus redirectors into the application's descriptor to enable testing the application with Cactus.

This task currently merges only a subset of the definitions in a descriptor, based on the most common usage scenarios:
  • Context parameters: Any <context-param> element get inserted into the resulting descriptor verbatim.
  • Servlets and Filters: Both the actual definition of the servlet/filter as well as the mappings to URL patterns are merged. If the servlet or filter to inject is already present in the source descriptor, the initialization parameters are merged.
  • Resource References and Resource Environment References : Any <resource-ref> or <resource-env-ref> elements get inserted into the resulting descriptor verbatim.
  • Security Constraints: Any <security-constraint> elements get inserted into the resulting descriptor verbatim.
  • Login Configuration: If a <login-config> element is present, it will replace the corresponding element in the source descriptor.
  • Security Roles: Any <security-role> elements that are not already defined in the source descriptor are inserted into the resulting descriptor.
  • Environment Entries: Any <env-entry> elements get inserted into the resulting descriptor verbatim.
  • EJB References: Any <ejb-ref> or <ejb-local-ref> elements get inserted into the resulting descriptor verbatim.

Parameters

Name Description Required
srcfile The original deployment descriptor. Yes
destfile The destination file. Yes
mergefile The descriptor containing the definitions that should be merged into the descriptor. Yes
encoding The character encoding of the destination file. If this attribute is ommitted, the character encoding of the source file will be applied. No
force By default the task checks the modification times of the files before performing the merge. Set this attribute to false to perform the merge regardless of whether the destination file seems to be up to date. No
indent Whether the resulting XML should be indented when written to the destination file. No, the default is false

Nested Elements

xmlcatalog

The xmlcatalog element can be used to perform Entity and URI resolution. This is a built-in Ant type. See the Ant documentation for details. The webxmlmerge task resolves the DTDs of web-app descriptors (version 2.2 as well as 2.3) automatically to copies stored in the JAR. So normally, you shouldn't need to specify a nested xmlcatalog element. Further, actually specifying it will disable the default behaviour, and you'll need to provide the web-app DTDs yourself.

Examples

The following example demonstrates the simplest-possible use of the task.
<webxmlmerge srcfile="${src.conf.dir}/web.xml"
    destfile="${build.conf.dir}/web.xml"
    mergefile="${cactus.ant.home}/confs/web.xml"/>
To improve speed of the parsing process and enable offline operation, you should specify local paths to the web-app DTDs using a nested xmlcatalog element:
<webxmlmerge srcfile="${src.conf.dir}/web.xml"
    destfile="${build.conf.dir}/web.xml"
    mergefile="${cactus.ant.home}/confs/web.xml">
  <xmlcatalog>
    <dtd publicid="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
        location="${src.dtd.dir}/web-app_2_2.dtd"/>
    <dtd publicid="-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
        location="${src.dtd.dir}/web-app_2_3.dtd"/>
  </xmlcatalog>
</webxmlmerge>
The following example demonstrates using an xmlcatalog by reference, so that it can also be used in other tasks (for example to validate the descriptors). In addition, the indent attribute is set to yes to achieve better readability of the resulting descriptor.
<xmlcatalog id="j2ee.dtds">
  <dtd publicid="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
      location="${src.dtd.dir}/web-app_2_2.dtd"/>
  <dtd publicid="-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
      location="${src.dtd.dir}/web-app_2_3.dtd"/>
</xmlcatalog>

<webxmlmerge srcfile="${src.conf.dir}/web.xml"
    destfile="${build.conf.dir}/web.xml"
    mergefile="${cactus.ant.home}/confs/web.xml"
    indent="yes">
  <xmlcatalog refid="j2ee.dtds"/>
</webxmlmerge>