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:
- 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 nestedxmlcatalog
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, theindent
attribute is set toyes
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>