Programming Jakarta Struts

The Web Application Deployment Descriptor

The web application deployment descriptor conveys configuration information between application developers, deployers, and assemblers. Web containers also use the descriptor to configure and load web applications when the container is started.

All servlet containers that are compliant with the 2.3 Servlet specification are required to support the following types of deployment information:

• Initialization parameters

• Session configuration

• Servlet declarations

• Servlet mappings

• Application lifecycle listener classes

• Filter definitions and mappings

• MIME type mappings

• Welcome file list

• Error pages

Security configuration information is not required unless the servlet container is part of a J2EE implementation. The following elements are not required unless the servlet container is using JSP pages or is part of a J2EE application server:

• Tag library mappings

• JNDI References

Warning

Much of the functionality described in this list was added in the 2.3 version of the Servlet specification. If you are using a 2.2-compliant container, it will not be available to you. Struts 1.1 supports the 2.2 and 2.3 Servlet specifications.

Web Application Deployment Descriptor DTD

The format for both the web application deployment descriptor and the Struts configuration file is based on a Document Type Definition (DTD), which defines the legal building blocks that may be used in the XML files. From the DTD point of view, all XML documents, including the web application deployment descriptor and the Struts configuration file, are made up of the following elements:

• Elements

• Tags

• Attributes

• Entities

• PCDATA

• CDATA

Using these components, DTDs help to specify valid and well-formed XML documents.^[6] The DTD for the 2.3 web application deployment descriptor can be downloaded from http://java.sun.com/dtd/index.html.

The following DTD declaration shows the top-level elements that make up the deployment descriptor for a web application:

<!ELEMENT web-app (icon?, display-name?, description?,
   distributable?, context-param*, filter*, filter-mapping*,
   listener*, servlet*, servlet-mapping*, session-config?, mime-
   mapping*, welcome-file-list?, error-page*, taglib*, resource-
   env-ref*, resource-ref*, security-constraint*, login-config?,
   security-role*, env-entry*, ejb-ref*, ejb-local-ref*)
>

The web-app element is the root of the deployment descriptor for a web application. The other elements inside the parentheses are child elements, which must be placed inside the root web-app element within the XML file. The symbols next to the child elements indicate the allowed multiplicity of the child elements within the XML file. Table 4-1 provides a brief explanation of the symbols.

Tip

The order of the child elements is implied by their order inside of the parent element. For instance, in the web-app syntax, the servlet element must come before the servlet-mapping element, the servlet-mapping element must come before the taglib element, and so on.

Table 4-1.  Multiplicity symbols of child elements within a DTD

Symbol	Meaning
No symbol	Indicates that the child element must occur once and only once within the parent element.
+	Declares that the child element can occur one or more times within the parent element.
*	Declares that the child element can occur zero or more times within the parent element. This symbol is used quite often.
?	Declares that the child element can occur zero or one time within the parent element. In other words, the child element is optional. This symbol is used quite often.

---

^[6] A well-formed XML document is one that is properly formatted with all beginning tags closed with end tags, all attributes quoted properly, all entities declared, and so on. When an XML document is well-formed, it is easier for a computer program to parse it and deliver it over a network. A valid XML document is one that declares a DTD and adheres to the rules set forth in that DTD. For more information, see Java & XML by Brett McLaughlin (O’Reilly).