If you've taken a look at J2EE and JavaServer Pages technology, and want to examine JSP more closely, you've come to the right place. This article, the first of two parts, is excerpted from chapter three of Beginning J2EE 1.4 From Novice to Professional, written by James L. Weaver, Kevin Mukhar, and Jim Crume (Apress, 2004; ISBN: 1590593413).
JavaServer Pages - Try It Out: Deploying the Web Application in Tomcat (Page 6 of 7 )
Deploying applications to a Tomcat stand-alone server is simpler, but it does require us to write a special XML file, known as a deployment descriptor. This file is also required by the J2EE server, but the Deployment Tool creates it for us, so we dont need to write it by hand.
Firstly, then, if you are deploying to a Tomcat stand-alone, you need to write a deployment descriptor for the web application. Development descriptors are XML files that contain configuration information about the entire web application. We will look at development descriptors in more detail in Chapter 5. Here is the deployment descriptor for our JavaFAQ application. This file is called web.xml and is placed in the applications WEB-INF directory:
<?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/dtd/web-app_2_3.dtd"> <web-app> <!-- this is the deployment descriptor for Chapter 3 Try It Out example 1 --> <welcome-file-list> <welcome-file>welcome.jsp</welcome-file> </welcome-file-list> </web-app>
If the J2EE server is running, shut it down.
If you created the directory structure we described earlier in the chapter (when we looked at the source code for the application) within the Tomcat /webapps directory, then you are finished. Go to step 5.
If the application directory is not under the Tomcat /webapps directory, you can do one of two things:
Either copy the directory structure to Tomcat /webapps. Or navigate to the top-level directory of the web application. For example, if the highest directory of the application is /Ch03, you would navigate into that directory.
Now create the Web Archive manually:
> jar cf Ch03.war *
Copy the .war file to the Tomcat /webapps directory.
Start the Tomcat server. When it is started, open a browser window and enter the address http://localhost:8080/Ch03. The welcome.jsp file will load as shown in the J2EE example.
How It Works
Since youll need to write a deployment descriptor for any web applications you want to deploy to a Tomcat stand-alone, lets take a moment to look at the web.xml file in this example. First come the standard XML declaration and document type declaration, which you can use for any JSP deployment descriptors:
<?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/dtd/web-app_2_3.dtd">
Next, comes the XML content of the file. The root XML element is called <web-app>, and in this case contains only a single child element, <welcome-file-list>:
This element lists the files that will be served to any client that simply enters the application context from a browser. These files are referred to as welcome files. For example, an address like http://localhost:8080/Ch03 does not reference any resource within the web application root context, /Ch03. Anyone who enters a URL like this will be served a welcome file from the list. If multiple files are listed in the welcome file list, the server will respond with the first file in the welcome file list that it finds.
I will cover specific elements of the deployment descriptor as they apply, but we will look at deployment descriptors in more detail in Chapter 5. You can also find more information about the deployment descriptor in the documentation for Tomcat, and the JSP and Servlet specifications.
When you load the welcome page, you probably saw that the links in that page do not reference actual resources within the application. If you clicked on one of the links, you probably received an HTTP 404 error in the browser. You did not see the error page, because the problem was a Resource Not Found in the server, not an uncaught exception in the page.
The elements in the deployment descriptor must follow a particular order specified by a Document Type Definition (DTD) (JSP 1.2 and earlier), or an XML Schema (JSP 2.0). If the elements are not in the correct order, the server will not start the application. In Chapter 5 in this book, well look at the correct order as defined by the DTD in the Servlet 2.3 specification.
To actually deploy the application to Tomcat, we need to copy the files to Tomcats /webapps directory. If you dont want to store the applications files directly in this directory, you can deploy the application by packaging all the files into a web archive, or WAR, file. The WAR is a convenient way to package all the files and components that make up a web application into one archive. All JSP containers know how to read and deploy web applications from the WAR. Thus, deploying a web application is as simple as creating the archive with the correct application directory structure and putting it into the correct directory location for the container. The directory structure of the web application, and thus the WAR, is defined in the servlet specification. Likewise, the deployment descriptor is defined by the specification. When you use a tool like the J2EE Deployment Tool, it takes care of creating the correct directory structure and deployment descriptor for you, but you need to create it manually if youre deploying to a Tomcat stand-alone.
In general, the structure of your application will look like this:
app_context/ public web resources WEB-INF/ web.xml tlds/ tld files lib/ archives used by application classes/ class files used in application
The directory at the top of the structure defines the web application context. The application context provides a separation between different web applications. Under the application context directory are the public files of the application. This will generally include the HTML and JSP pages of the application. Under the application context is the WEB-INF directory. This directory contains the deployment descriptor web.xml and other files that are not publicly accessible by clients of the application. There can be any number of directories under WEB-INF, but three common ones are shown above. The tlds directory is not required, but is a commonly used directory for keeping tag library descriptor files (see Chapter 4). The lib directory is used for Java archives (.jar files) that are used by the web application. Finally, the classes directory is used for class files in the web application.