Deployment Descriptor

The web.xml file is the deployment descriptor for Java web applications. It is an XML document that contains information about the web applications configuration and set up information for each servlet.

Below is a an example of a typical web.xml file.

<web-app>

The configuration file in this instance is broken up into 4 distinct sections. The servlet section

Servlet Tags

The <servlet> tag alerts the servlet container to the availability of a servlet class. Inside the <servlet>

tag is the <servlet-name> and <servlet-class> tags. The servlet name is used to provide a unique identifier for the servlet class that is identified. The name is later referenced in the servlet mapping tag set to map the servlet class to a particular URL. The servlet class must provide the full package name for the servlet. The identified class must be found within the WEB-INF/classses directory or within a JAR file in the WEB-INF/libs directory. If it is not found then the deployment will fail.

Every servlet must have its own set of <servlet> tags.

<servlet>

<servlet-name>TestServlet</servlet-name>

<servlet-class>net.nplus1.acme.TestServlet</servlet-class>

</servlet>

In addition the <servlet> tag supports the passing of initial parameter data to the servlet. These values are made available at run time.

<servlet>

The <init-param> tag shown above allows the developer to pass parameters to the servlet at run time. The parameters are grouped into name / value pairs that can be accessed by the servlet through the ServletConfig object. The ServletConfig object is created and maintained by the base implementation of HttpServlet. Therefore a local servlet call to getServletConfig() allows access to the object. Below is an example of retrieving initial parameters from within a servlet.

Servlet Mappings

The <servlet-mapping> tag is used to match servlets with a particular URL. The <servlet-name>

tag contains the name of a servlet defined in the <servlet> tag. The <url-pattern> tag provides a specific URL to map to the named servlet. The goal is to map a URL to the servlet’s class.

<servlet-mapping>

When a web application is deployed, the servlet container loads the URL patterns into a table in memory. When an end user makes a request on the server, it looks in that table to see if the URL requested matches one of the servlet defined URLs. From the table it can retrieve the appropriate servlet class. If the servlet hasn’t been previously invoked, the container uses reflection and creates a new instance of the servlet and adds it to the table.

To provide additionally flexibility, the <url-pattern> tag can use “*” as a wild card character.

Allowing multiple requests to be directed to the same servlet. Look at the following pattern.

<url-pattern>/actions/*</url-pattern>

Anything after the actions part of the URL will be redirected to the same servlet. Therefore any of the following partial URLs would match the pattern.

/actions/foo.html

All of these URLs be redirected to the servlet defined in the servlet-mapping.

Note About URLs All web applications have a context path which identifies it from other web applications deployed to the servlet container. On JBoss the default context path is defined by the name of the war file³. Therefore if acme.war and test.war are both deployed to the servlet container, one would have a context path of acme while the latter would have a path of test.

http:://nplus1.net/acme/shopping/cart.html http:://nplus1.net/test/test.jsp

In this case “acme” and “test” within the URL path are used to determine which web application is being accessed. The context path only defines part of the URL. The servlet path is the section of the URL which goes from the context path to the point it matches a servlet. This is the path which is defined in the url-pattern. Therefore for the first URL the following url-pattern would be necessary.

<url-pattern>/shopping/cart.html</url-pattern>

If a wild card is used in a <url-pattern tag>, the servlet path only goes to the point where the pattern matches. The rest of the URL is known as the path info. Take the following URL.

http:://nplus1.net/acme/shopping/checkout/cart.html

Below is the shopping servlet’s url-pattern.

<url-pattern>/shopping/*</url-pattern>

In this instance, the context path is /acme. The servlet path is /shopping and the path info is /checkout/cart.html.

Session Config

As noted before, the HTTP protocol is a stateless protocol. There is no way to tell if any two requests are coming from the same user. To be able to maintain state between multiple client requests, Java containers provides a session object. The session object is mapped to a cookie stored on the client’s browser. The concept of sessions will be studied later.

The web.xml deployment descriptor provides a section, <session-config>, for configuring the behavior of the session object. It allows a <session-timeout> value to be configured.

<session-config>

<session-timeout>3600</session-timeout>

</session-config>

The session timeout is used to determine how long the cookie on the browser side is valid. The timer starts at the time the last request was made on the server. When a user makes a future request, the container checks to see if the user has exceeded the allotted time. If so the session is invalidated and resource are released back to the system.

The timeout of a session is experienced by people who use on-line banking solutions. If one doesn’t continue using the service frequently, the service logs the user out of the system. In this case the session has expired and the user must log in again to create a new session.

The <session-timeout> in the configuration file is marked in seconds. Therefore a session timeout of 3600 is the equivalent to 1 hour.

Welcome File List

Not all URL requests made by the end user point to an exact resource. Sometimes the URL will point to a directory structure. Since a directory is not a resource which can be returned, the container will search for a default file within the directory.

The file the container searches for is defined in the deployment descriptor within the <welcome-file-list> tag.

<welcome-file-list>

<welcome-file>index.html</welcome-file>

<welcome-file>index.jsp</welcome-file>

</welcome-file-list>

Each file is separated by a welcome-file tag. The servlet container will search for each file in the order in which they appear within the file list. In the example above the servlet container will search for the index.html file first. If it doesn’t find the file, it searches for the index.jsp file. If neither file is found then the system will return the contents of the directory or an error page depending on the configuration of the servlet container.