Deploying J2EE Web Applications

J2EE technology has grown over a number of years and so has the number of servlet containers and application servers. Fortunately, there is a standard procedure to deploy J2EE applications to ease the developers from vendor locks. In this article, we'll take you through how to manually deploy a J2EE Web application on Apache Tomcat 5. The purpose of this article is to give you a clear understanding of how to deploy server-side components like servlets, JSPs and tag libraries. We'll also discuss some other alternatives of
deploying Web applications. We, however, assume that you have a basic understanding of servlets and
JSPs. 

Web application directory structure

It's important to understand the Web application directory structure. The name of our Web application is 'pcquest'. The 

directory structure in the box shows you as to where different components are placed. Note that the resources placed inside the /pcquest directory are publicly available whereas the servlets, tag libraries, listeners and beans placed inside the WEB-INF directory are private to the Web application, so any attempt to directly access these constrained resources gives '404 Not Found' error.

Web application deployment descriptor

The Web application deployment descriptor (or DD) is an XML file named 'web.xml' located in the private WEB-INF directory. It
describes the configuration information for the entire Web application. Note that each Web application has a separate DD (web.xml) file. It must be a valid XML document, according to the DTD for J2EE applications. The information contained in the DD includes several elements such as servlet initialization parameters, session configuration, servlets mapping, welcome files, error pages and security. 

Servlet mapping 

Servlet mapping is used to hide your servlets from direct  access. You must protect your servlets from direct access from others by using URL mapping. The DD gives you a way to declaratively modify your application without changing the source code. Hard coding the real path and file name in your JSPs and HTML pages makes it difficult to maintain if you move things to different directory. Instead if you map names, you have this facility without
worrying about changing the client code that refers to the old location of your pages. Secondly, there will be a security breach if your clients can navigate directly to the servlets without going through the right pages. If the end user can see the real path, he can type that into the browser and access it directly. 

Directory structure created  /pcquest-This is the root directory of the Web application. All JSP and XHTML files are stored here. /pcquest/WEB-INF-This contains all resources related to the application that are not in the document root of the application. This is where your Web application deployment descriptor (web.xml) is located. Note that the WEB-INF directory is not part of the public document. No files from here can be served directly to a client. /pcquest/WEB-INF/classes-This is where servlet class files and utility classes (beans, listeners etc) lie. /pcquest/WEB-INF/lib-Contains Java Archive files (JARs) that the Web application depends upon.

The developer defines the actual servlet class name that often comprises the package structure where the file is placed. The 

deployer creates a name known only to him. This is a fake name, used to map the public URL used by the client. Finally, the client sees the URL of the servlet but he has no idea how that name maps to the real servlet class name. It is also fake, used in JSPs and HTML pages.

DownloadServlet com.pcquest.DownloadStarterServlet DownloadServlet /download/start.do >

Configuring servlet initialization

Servlets are initialized at the first request. The init() method is guaranteed to be called before doGet() or doPost() methods. This means that the first client has to suffer the pain of class loading, instantiation and initialization before the container serves any client request by spawning a new thread for execution. If you want the servlets to be loaded at deploy time or server restart time, use the element in the DD. Any value greater than zero for tells the container to initialize the servlet when the application is deployed or the container is restarted. 

ClientListener

com.pcquest.ClientListenerServlet

1

If you want to preload multiple servlets, the value of determines the order in which they are initialized. Any value greater than zero means load early. 

Configuring welcome files

You can configure welcome pages for your Web application in the DD. You can specify a list of welcome pages that the container chooses when the client enters a partial URL.

index.html 

default.jsp

It will be difficult if you have to specify a specific default page or JSP for each directory. Instead, you specify a list of pages you want the container to look for in whatever directory the partial request is for. Now, whenever a client enters a partial URL involving only the directory, but not a specific resource in the directory, the container uses the first match, starting with the first welcome file listed in the . 

Configuring error pages

You can make a Web application act in a user-friendly way instead of displaying ugly error messages and long stack trace. The web.xml DD provides an elegant mechanism to customize the error pages. 

java.lang.NullPointerException

/jsp/errors/nullPointerError.jsp

404/jsp/errors/notFoundError.jsp

This configures an error page that's called when there's a
NullPointerException.

Packaging a Web application

Moving the internal directory structure of a Web application from one container to the other can be a problem. Fortunately, the J2EE specification addresses this issue with the WAR (Web ARchive) files. A Web application needs to be archived into a single WAR file prior to its deployment. A WAR file is a snapshot of your Web application in a portable and compressed form ready for distribution. A WAR file is actually a JAR file, a JAR with a .war extension. WAR files have become a de-facto standard for packaging and deploying J2EE Web applications. In Tomcat, the name of the WAR file becomes the Web application name. Note that the Web applications deployed through the WAR files have a META-INF directory under the Web application context. Following are the steps involved in packaging and deploying a Web application.

Step 1 Change to the root directory of your Web application. In this case the root directory would be
CATALINA_HOME/

webapps/pcquest/

Step 2 Archive the web application: jar-cvf pcquest.war

Step 3 Copy the resulting WAR file, pcquest.war, to the CATALINA
_HOME/webapps directory

Step 4 Restart Tomcat

Note that if you are deploying the WAR file to the Tomcat installation that you were developing in, first remove it from the webapps directory. Tomcat then unpacks it and creates the context directory. 

Conclusion

If you are using a J2EE deployment tool that lets you deploy your application through a series of wizard screens, then your container uses that information to build the XML based DD (web.xml), build the necessary directory structures and copy your files in to appropriate locations. Developers use a build tool like ANT for deployment but even then you need to know the directory structure and direct ANT. Deploying a Web application by placing a WAR file in the right directory frees you from copying every directory and file separately. Moreover, archiving a Web application into a single WAR file is the most standard procedure that ensures vendor transparency.

Kunal Jaggi, Sun Certified Java 2 Programmer