by Matt Horn
Technical Writer
Macromedia
Deployment Descriptor Overview
Deployment descriptors are text-based XML files whose elements
describe how to deploy and assemble components into a specific
environment. They also contain information about the components
that can specify settings not contained in the code of the
components themselves, such as initialization parameters and
security settings.
This section explains the various types of deployment descriptors
found in J2EE-compliant systems and then focuses on the
web.xml file, the web component deployment descriptor.
Types of deployment descriptors
Deployment descriptors come in several flavors as defined
by the J2EE specification. There are three major deployment
descriptors, which correspond to three major pieces of the
J2EE:
- J2EE application deployment descriptor. J2EE
applications contain one or more J2EE modules and one
J2EE application deployment descriptor. The J2EE application
deployment descriptor is stored as /META-INF/application.xml
and is defined in the J2EE specification. Its major function
is to point to the modules within the application. J2EE
applications are typically stored and deployed as enterprise
application archive (EAR) files.
- EJB module deployment descriptor. EJB
modules contain one or more EJB components. The EJB module
deployment descriptor is stored as /META-INF/ejb-jar.xml
and is defined in the EJB specification. Its major function
is to define and configure EJBs. EJB modules are typically
stored and deployed as Java archive (JAR) files.
- Web module deployment descriptor. Web
modules contain one or more web components (such as servlets,
JSPs, or HTML files). The web module deployment descriptor
is stored as /WEB-INF/web.xml and is defined in the Servlet
specification. Its major function is to define the web
component settings. Web modules are typically stored and
deployed as web application archive (WAR) files.
This article does not address the J2EE application client
module and J2EE connector module, which also have their
own deployment descriptors. Furthermore, Tag Library Descriptor
(TLD) files which describe custom JSP tag libraries are
not discussed.
The following illustration shows two web modules, app1.war
and app2.war, each containing an assortment of web components
(such as JSPs, and servlets) as well as static web files
(HTML files and GIFs), within a J2EE application. It also
shows an EJB module with EJB components (app_ejbs.jar).
Notice that just as each web and EJB module has its own
deployment descriptor, so does the J2EE application.
Why you need deployment descriptors
Deployment descriptors relate installation and configuration
information about applications to the application servers.
They can also be used to convey information about the application
to other people involved in the development process.
If you want to create an application that can be deployed
without the headache of manually configuring its components,
then packaging it as a WAR, JAR, or EAR file is the best
approach. Each of these files requires a deployment descriptor.
Overlapping elements
The following bulleted lists are meant to show the overlap
of deployment descriptor elements.
Common elements in all descriptors (web.xml,
application.xml, and ejb- jar.xml):
- Icons
- Description
- Display name
Elements in only web.xml and ejb-jar.xml
deployment descriptors:
- Naming environment entries
- EJB references
- Connection factory references
- Security elements
Elements in application.xml deployment descriptor
only:
- Module descriptions
- Security roles
Elements in web.xml deployment descriptor
only:
- Servlet definitions
- Servlet mappings
- Error pages
- Form-based authentication configuration
Elements in ejb-jar.xml deployment descriptor
only:
- Transaction elements
- Persistence elements
As you can see, there can be overlapping of elements in
the deployment descriptors. Each of the modules have their
own common elements such as descriptions, icons and display
names. While these elements share element names and syntax,
it is important to remember that they affect only the module
whose deployment descriptor they are in.
However, sometimes the modules define elements that interact
with other module's elements. For example, the application.xml,
ejb-jar.xml and web.xml files can all define security roles.
It is the role of the application assembler to make sure
that the descriptors complement one another rather than
provide contradictory configuration information.
For complete descriptions of the various XML files and
their allowed values, you can view the DTDs in the module
specifications. The elements of the web.xml file are described
in detail in "web.xml Elements".
The rest of this article provides information on the web
application deployment descriptor file. For information
on the EJB and J2EE deployment descriptors, refer to their
respective specifications.
Introduction to the web.xml File
The web.xml file is used by the J2EE application server
during deployment of a web module. It describes the web
components used by that web module, environment variables,
and security requirements. This information is stored as
/WEB-INF/web.xml. For example, the default application's
deployment descriptor might be stored as /usr/jrun/servers/default/default-app/WEB-INF/web.xml.
You must add a web.xml deployment descriptor to any WAR
file you want to deploy as a web application. You can then
add your web module to a J2EE application, which has its
own deployment descriptor (application.xml) in addition
to the web module's web.xml.
Who creates web.xml files
JRun and the web component creator share in the creation
of the web.xml deployment descriptor. Some but not all of
the settings in the web.xml file can be created or edited
programmatically by using JMC panels. For example, there
is currently no panel to write user/role/group information
to the web.xml file.
For detailed information on which elements in a web.xml
file can be defined by JMC panels, review the descriptions
in the following sections. A table in third
part of this series lists all the primary elements and
shows which JMC panel defines that element.
web.xml Elements
The web.xml file can define the following information,
as defined by the web application deployment descriptor
data type definition (DTD) in the Servlet specification:
