11.2. The Web App Geronimo Deployment Plan

11.2. The Web App Geronimo Deployment Plan
	Chapter 11. Web Applications (WARs) [DRAFT (1.0)]

The Geronimo deployment plan for a web application is an XML document. It is defined by the geronimo-web-1.0.xsd schema, which can be found in the schema/ subdirectory of the main Geronimo installation directory. The deployment plan for a web application may be:

Included in the web application WAR, in which case it should be named WEB-INF/geronimo-web.xml
Included in the EAR and referenced by an alt-dd element of the EAR deployment plan (see Section 15.3.2, “Configuring Application Modules”)
Saved as a separate file and provided to the deploy tool when the module is deployed
Created from scratch using a JSR-88 configuration tool, in which case the tool manages saving and loading the deployment plan and passing it to the server when the EJB JAR is deployed. For more information on JSR-88 tools see Section 10.6, “JSR-88 Configuration & Deployment Tools”.

The deployment plan should always use the Geronimo web namespace, and it typically requires elements from the Geronimo Naming namespace. Additionally, it has a required attribute to identify its configuration name, and an optional attribute to select a parent configuration. A typical web application deployment plan looks like this:

WEB-INF/geronimo-web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app
  xmlns="http://geronimo.apache.org/xml/ns/j2ee/web-1.0"
  xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.0"
  xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0"
  xmlns:security="http://geronimo.apache.org/xml/ns/security-1.1"
  configId="MyConfigName"
  parentId="ParentConfigName">
  ...
</web-app>

The attributes here are:

xmlns: The main namespace for the deployment plan, which should generally be http://geronimo.apache.org/xml/ns/j2ee/web-1.0 (it's possible to use a namespace that will restrict the web application to only deploy in a Geronimo configuration using Tomcat or only in Jetty, but that's generally not desirable -- see Section 11.5, “Forcing Web Application Deployment to Tomcat or Jetty”).
xmlns:sys: A secondary namespace, used to identify the common elements for third-party libraries and custom services. If present, this should always be set to http://geronimo.apache.org/xml/ns/deployment-1.0
xmlns:naming: A secondary namespace, used to identify the common elements for resolving EJB references and resource references. If present, this should always be set to http://geronimo.apache.org/xml/ns/naming-1.0
xmlns:security: A secondary namespace, used to identify the common elements for security realm settings. If present, this should always be set to http://geronimo.apache.org/xml/ns/security-1.1
configId: A unique name identifying this module. If deployed as a standalone WAR, this name can be passed on the server command line to activate this web application when the server starts.
parentId: Identifies the parent configuration for this web module (the value specified here should match the configId for that module). If deployed as a standalone WAR, this can be used to make the web application depend on another module such as a standalone EJB JAR or J2EE Connector (or it should otherwise be omitted or set to the usual parent for J2EE modules, geronimo/j2ee-server/1.0/car). If deployed as part of an EAR this is usually not necessary, as EAR configuration will be the parent of this module.

Geronimo understands deployment plans that omit namespace prefixes, so the naming and security namespace declarations are not required even if those kind of elements are used. However, this is a convenience, and for a deployment plan to be considered valid XML by tools other than Geronimo, proper namespaces must be used for all child elements.


Chapter 11. Web Applications (WARs) [DRAFT (1.0)]		11.3. Structure of the Deployment Plan