Friday, April 29, 2011

Chapter 48: Elements of the Deployment Descriptor

In the previous chapter, we used a term web.xml and called it the Deployment Descriptor. This is probably the most important part of any web application. Even if you have all your servlets, JSPs, Jars etc set up properly, the system wouldn't run fine unless you set up the deployment descriptor properly. This is exactly what we are going to learn in this chapter.

So, lets get started!!!

Where is the Web.xml file located?

The web.xml file is located in the WEB-INF directory whether in the file system or in a WAR file. This file contains a total of 77 elements, but don't get scared just yet because the exam doesn't expect you to know or memorize all of them.

The main elements of a Web.xml file are:

Note: DTD stands for Document Type Definition and is a term used in XML that is used to build XML code blocks.

Element XML DTD
context-param < ! ELEMENT context-param (param-name, param-value, description?) >
listener
< ! ELEMENT listener (listener-class) >
< ! ELEMENT listener-class (#PCDATA) >
Servlet
< ! ELEMENT servlet (icon?, servlet-name, display-name?, description?, (servlet-class|jsp-file), init-param*, load-on-startup?, run-as?, security-role-ref*)>
< ! ELEMENT servlet-name (#PCDATA) >
< ! ELEMENT servlet-class (#PCDATA) >
< ! ELEMENT load-on-startup (#PCDATA) >
< ! ELEMENT run-as (description?, role-name) >
< ! ELEMENT security-role-ref (description?, role-name, role-link?) >
servlet-mapping < ! ELEMENT servlet-mapping (servlet-name, url-pattern) >
session-config
< ! ELEMENT session-config (session-timeout?) >
< ! ELEMENT session-timeout (#PCDATA) >
welcome-file-list < ! ELEMENT welcome-file (#PCDATA) >
error-page
< ! ELEMENT error-page ((error-code | exception-type), location) >
< ! ELEMENT error-code (#PCDATA) >
< ! ELEMENT exception-type (#PCDATA) >
Taglib
< ! ELEMENT taglib (taglib-uri, taglib-location) >
< ! ELEMENT taglib-location (#PCDATA) >
< ! ELEMENT taglib-uri (#PCDATA) >
security-constraint
< ! ELEMENT security-constraint (display-name?, web-resource-collection+, auth-constraint?, user-data-constraint?) >
< ! ELEMENT auth-constraint (description?, role-name*) >
< ! ELEMENT web-resource-collection (web-resource-name, description?, url-pattern*, http-method*) >
< ! ELEMENT user-data-constraint (description?, transport-guarantee) >
login-config < ! ELEMENT login-config (auth-method?, realm-name?, form-login-config?) >
security-role < ! ELEMENT security-role (description?, role-name) >
As previously stated, you don't have to know/remember the entire DTD. Out of the root element you should focus on these:

C = < context-param >
L = < listener >
S = < servlet >
S = < servlet-mapping >
S = < session-config >
W = < welcome-file-list >
E = < error-page >
T = < taglib >
S = < security-constraint >
L = < login-config >
S = < security-role >

Now that we know the important components of the deployment descriptor, let us take a look at each of them in detail.

context-param

The context-param element declares the Web application's servlet context-initialization parameters.

Element

< !ELEMENT context-param (param-name, param-value, description?) >

Example

< web-app >
...
< context-param >
< param-name >TOMCAT_ROOT< /param-name >
< param-value >C:\dev\java\jakarta-tomcat-4.0.1
< /param-value >
< /context-param >
< context-param >
< param-name >Support< /param-name >
< param-value >helpdesk@mycompany.com< /param-value >
< /context-param >
...
< /web-app >

listener

The listener element defines the deployment properties for a Web application listener bean.

Element

< !ELEMENT listener (listener-class) >
< !ELEMENT listener-class (#PCDATA) >
Example
< web-app >
...
< listener >
< listener-class >listeners.MyListener< /listener-class >
< /listener > ...
< /web-app >

Servlet

The servlet element is how you define a servlet in a Web application. The servlet element establishes a mapping between a servlet name and the fully qualified name of the servlet class. Of course, you don't have to name all your servlets in the web.xml file. However, there are servlets that you may need defined here so the container can load them upon starting (load-on-startup element), for example.

Element

< !ELEMENT servlet (icon?, servlet-name, display-name?, description?, (servlet-class|jsp-file), init-param*, load-on-startup?, run-as?, security-role-ref*) >
< !ELEMENT servlet-name (#PCDATA) >
< !ELEMENT servlet-class (#PCDATA) >
< !ELEMENT load-on-startup (#PCDATA) >
< !ELEMENT run-as (description?, role-name) >
< !ELEMENT security-role-ref (description?, role-name, role-link?) >
Example

< web-app >
...
< servlet >
< servlet-name >
MyTestServlet
< /servlet-name >
< servlet-class >
MyTestServlet
< /servlet-class >
< /servlet >
...
< /web-app >


servlet-mapping

The servlet-mapping element defines a mapping between a servlet and a URL pattern. When a request is received by the container it must determine which servlet should handle it. Using the deployment descriptor, you can map certain paths (aliases) to a specific servlet. You define this mapping with the servlet-mapping element. The alias is appended after the context root in an HTTP request URL.

Element

< !ELEMENT servlet-mapping (servlet-name, url-pattern) >

Example

< web-app >
...
< servlet-mapping >
< servlet-name >
MyTestServlet
< /servlet-name >
< url-pattern >
/testServlet
< /url-pattern >
< /servlet-mapping >
...
< /web-app >

session-config

The session-config element defines the session parameters for this Web application such as the session timeout, which defines the default session timeout interval for all sessions created in this Web application.

Element

< !ELEMENT session-config (session-timeout?) >
< !ELEMENT session-timeout (#PCDATA) >


Example

< web-app >
...
< session-config >
< session-timeout >30< /session-timeout >
< /session-config >
...
< /web-app >

welcome-file

The welcome-file element contains a filename to use as a default file, such as index.html.

Element

< !ELEMENT welcome-file (#PCDATA) >

Example

< web-app >
...
< welcome-file-list >
< welcome-file >index.jsp< /welcome-file >
< welcome-file >index.html< /welcome-file >
< welcome-file >index.htm< /welcome-file >
< /welcome-file-list >
...
< /web-app >

error-page

The error-page element contains a mapping between an error code or exception type to the path of a resource in the Web application.

Element

< !ELEMENT error-page ((error-code | exception-type), location) >
< !ELEMENT error-code (#PCDATA) >
< !ELEMENT exception-type (#PCDATA) >

Example

< web-app >
...
< error-page >
< error-code >404< /error-code >
< location >/NotFoundErrorPage< /location >
< /error-page >
...
< /web-app >

taglib

The taglib element is used to describe a JSP tag library, including the tag library location (Tag Library Description file) and the URI for it which is a unique namespace identifying a tag library used in the Web application.

Element

< !ELEMENT taglib (taglib-uri, taglib-location) >
< !ELEMENT taglib-location (#PCDATA) >
< !ELEMENT taglib-uri (#PCDATA) >

Example

< web-app >
...
< taglib >
< taglib-uri >
http://www.yourcompany.com/yourTagLibrary
< /taglib-uri >
< taglib-location >
/WEB-INF/yourTagLibrary.tld
< /taglib-location >
< /taglib >
...
< /web-app >


security-constraint

The security-constraint element is used to associate security constraints with one or more Web resource collections such as a security role and user roles that should be permitted access to this resource collection.

Element

< !ELEMENT security-constraint (display-name?, web-resource-collection+, auth-constraint?, user-data-constraint?) >
< !ELEMENT auth-constraint (description?, role-name*) >
< !ELEMENT web-resource-collection (web-resource-name, description?, url-pattern*, http-method*) >
< !ELEMENT user-data-constraint (description?, transport-guarantee) >

Example

< web-app >
...
< security-constraint >
< web-resource-collection >
< web-resource-name >All Users Allowed Area
< /web-resource-name >
< url-pattern >/allowed/*< /url-pattern >
< /web-resource-collection >
< auth-constraint >
< role-name >*< /role-name >
< /auth-constraint >
< /security-constraint >
...
< /web-app >

login-config

The login-config element is used to configure the authentication method that should be used, the realm name that should be used for this application, and the attributes that are needed by the form login mechanism.

Element

< !ELEMENT login-config (auth-method?, realm-name?, form-login-config?) >

Example

< web-app >
...
< login-config >
< auth-method >BASIC< /auth-method >
< realm-name >Authentication Servlet< /realm-name >
< /login-config >
...
< /web-app >

security-role

The security-role element contains the definition of a security role. The definition consists of an optional description of the security role, and the security role name.

Element

< !ELEMENT security-role (description?, role-name) >

Example

< web-app >
...
< security-role >
< description >
This role includes all customers who have a credit
line with us based on at least one previous purchase.
< /description >
< role-name >customer< /role-name >
< /security-role >
...
< /web-app >

Web Application Descriptor Example

Now that we have reviewed all the elements individually, let's look at a full example as to how a web applications deployment descriptor would look like. The following web.xml file includes all the previously listed elements. The majority of this descriptor comes by way of snippets from many samples that shipped with Tomcat.

Web.xml Code:

< ?xml version="1.0" encoding="ISO-8859-1"? >

< !DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/j2ee/dtds/web-app_2_3.dtd" >

< ! - - Deployment Descriptor for your Web Application -- >
< ! - - Some elements come from Tomcat examples. -- >

< web-app >

< ! - - General description of your web application -- >
< ! - - You won't be tested on these two tags, but you might see them -- >

< display-name >My Web Application< /display-name >
< description >
This is version X.X of an application to perform a wild and wonderful task,
based on servlets and JSP pages.
< /description >

< ! - - ======= Filter Definitions not on exam====== -- >

< ! - - ======= Context Initialization ============= -- >
< ! - - Context initialization parameters that define shared String constants used within your application, which can be customized by the system administrator who is installing your application. The values actually assigned to these parameters can be retrieved in a servlet or JSP page by calling: String value = getServletContext().getInitParameter("name"); where "name" matches the < param-name > element of
one of these initialization parameters.

You can define any number of context initialization
parameters, including zero.
-- >

< context-param >
< param-name >webmaster< /param-name >
< param-value >myaddress@mycompany.com< /param-value >
< description >
The EMAIL address of the administrator to whom
questions and comments about this application
should be addressed.
< /description >
< /context-param >

< ! - -=== Listener Definitions =================== -- >

< listener >
< listener-class >yourPackage.YourListener
< /listener-class >
< /listener >

< ! - - ==== Servlet Definitions ================= -- >

< ! - - Servlet definitions for the servlets that make up your web application, including initialization parameters. With Tomcat, you can also send requests to servlets not listed here with a request like this: http://localhost:8080/{context-path}/servlet/{classname} but this usage is not guaranteed to be portable. It also makes relative references to images and other resources required by your servlet more complicated, so defining all of your servlets (and defining a mapping to them with a servlet-mapping element) is recommended. Servlet initialization parameters can be retrieved in a servlet or JSP page by calling: String value = getServletConfig().getInitParameter("name"); where "name" matches the < param-name > element of one of these initialization parameters.

You can define any number of servlets, even zero.
-- >

< servlet >
< servlet-name >CustomerSupport< /servlet-name >
< servlet-class >yourPackage.CustomerSupport
< /servlet-class >
< /servlet >

< servlet >
< servlet-name >Authentication< /servlet-name >
< servlet-class >yourPackage.Authentication
< /servlet-class >
< security-role-ref >
< role-name >alias< /role-name >
< role-link >tomcat< /role-link >
< /security-role-ref >
< /servlet >

< servlet >
< servlet-name >Store< /servlet-name >
< servlet-class >yourPackage.Store< /servlet-class >
< init-param >
< param-name >itemCount< /param-name >
< param-value >0< /param-value >
< /init-param >
< init-param >
< param-name >listings< /param-name >
< param-value >true< /param-value >
< /init-param >
< load-on-startup >1< /load-on-startup >
< /servlet >

< ! - - ===== Servlet Mappings ===== -- >

< ! - - Define mappings that are used by the servlet container to translate a particular request URI (context-relative) to a particular servlet. The examples below correspond to the servlet descriptions above. Thus, a request URI like: http://localhost:8080/{contextpath}/graph will be mapped to the "graph" servlet, while a request like: http://localhost:8080/{contextpath}/saveCustomer.do will be mapped to the "controller" servlet. You may define any number of servlet mappings, including zero. It is also legal to define more than one mapping for the same servlet, if you wish to. -- >

< servlet-mapping >
< servlet-name >CustomerSupport< /servlet-name >
< url-pattern >/CustomerSupport< /url-pattern >
< /servlet-mapping >

< servlet-mapping >
< servlet-name >Authentication< /servlet-name >
< url-pattern >/Authentication< /url-pattern >
< /servlet-mapping >

< servlet-mapping >
< servlet-name >Store< /servlet-name >
< url-pattern >/commerce/store< /url-pattern >
< /servlet-mapping >

< ! - - === Default Session Configuration === -- >

< ! - - You can set the default session timeout (in minutes) for all newly created sessions by modifying the value below. -- >

< session-config >
< session-timeout >30< /session-timeout >
< /session-config >

< ! - - === Error Page Mappings === -- >

< error-page >< ! - - SC_PRECONDITION_FAILED -- >
< error-code >412< /error-code >
< location >/ErrorPage02< /location >
< /error-page >

< error-page >
< exception-type >java.lang.ArithmeticException
< /exception-type >
< location >/ErrorPage06< /location >
< /error-page >

< ! - - === Tag Libraries Configuration === -- >
< taglib >
< taglib-uri >
http://jakarta.apache.org/tomcat/examples-taglib
< /taglib-uri >
< taglib-location >
/WEB-INF/jsp/example-taglib.tld
< /taglib-location >
< /taglib >
< taglib >
< taglib-uri >
http://www.mycompany.com/taglib
< /taglib-uri >
< taglib-location >
/WEB-INF/taglib.tld
< /taglib-location >
< /taglib >

< taglib >
< taglib-uri >
http://www.yourcompany.com/yourTagLibrary
< /taglib-uri >
< taglib-location >
/WEB-INF/yourTagLibrary.tld
< /taglib-location >
< /taglib >



< ! - - === Security Constraints === -- >

< security-constraint >
< display-name >Example Security Constraint
< /display-name >
< web-resource-collection >
< web-resource-name >Protected Area
< /web-resource-name >
< ! - - Define the context-relative URL(s) to be protected -- >
< url-pattern >/jsp/security/protected/*
< /url-pattern >
< ! - - If you list http methods, only those methods are protected -- >
< http-method >DELETE< /http-method >
< http-method >GET< /http-method >
< http-method >POST< /http-method >
< http-method >PUT< /http-method >
< /web-resource-collection >
< auth-constraint >
< ! - - Anyone with one of the listed roles may access this area -- >
< role-name >tomcat< /role-name >
< role-name >role1< /role-name >
< /auth-constraint >
< /security-constraint >
< login-config >
< auth-method >BASIC< /auth-method >
< realm-name >Authentication Servlet< /realm-name >
< /login-config >

< security-role >
< description >Security role we are testing for
< /description >
< role-name >tomcat< /role-name >
< /security-role >

< ! - - === Environment Entries - not on exam === -- >


< ! - - === Default Welcome File List === -- >

< ! - - When a request URI refers to a directory, the default servlet looks for a "welcome file" within that directory and, if present, to the corresponding resource URI for display. If no welcome file is present, the default servlet either serves a directory listing, or returns a 404 status, depending on how it is configured.-- >

< welcome-file-list >
< welcome-file >index.html< /welcome-file >
< welcome-file >index.htm< /welcome-file >
< welcome-file >index.jsp< /welcome-file >
< /welcome-file-list >

< ! - - === Session Configuration === -- >

< ! - - Define the default session timeout for your application, in minutes. From a servlet or JSP page, you can modify the timeout for a particular session dynamically by using HttpSession.getMaxInactiveInterval(). -- >
< /web-app >


Previous Chapter: Chapter 47 - Introduction to Web Application Deployment

Next Chapter: Chapter 49 - Web Application Exceptions

No comments:

Post a Comment

© 2013 by www.inheritingjava.blogspot.com. All rights reserved. No part of this blog or its contents may be reproduced or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission of the Author.

ShareThis

Google+ Followers

Followers