Section 13.6. Configuring JSP Web Applications

13.6 Configuring JSP Web Applications

In ColdFusion development, when we talk about our applications, we generally mean the sites we're making. The application often consists of a number of .cfm templates, and may include other resources such as XML files, Verity collections, and so forth. You have the freedom to quickly crack out a single .cfm page and test it. You do not need to configure any special Web application to run it.

While you can do that in JSPs that you view in ColdFusion MX, in other containers you need to set up a Web application for each site you make. In this regard, it is similar to how you might make a project in an IDE. In Tomcat, you can do this manually or do it via the new Tomcat Administration Application, which is similiar to the ColdFusion Administrator.

13.6.1 The Tomcat Administration Application

The Administration tool is a Web application written in JSP that allows you to configure different settings regarding your Web applications. It also makes it very easy to create new Web applications. In this section we will walk through creating a new Web application that we can put JSPs into for testing.

There are a couple of steps required to configure a new Tomcat JSP application with the Administrator:

Create a new context
Create a physical directory
Create a web.xml file and other useful directories

We will walk through these steps now. To begin, open the Tomcat Administrator (shown in Figure 13.2).

In the Admin area, choose Service > Host.
To create a new Web application, you make a new context. To do this, click the Host (localhost) link. This will create the new context on the localhost server.

Note

Many Java Web application containers allow you to create multiple "servers"a somewhat confusing bit of terminology that simply means a discrete instance of the container that can maintain its own settings.
You must fill out four key items on the Context Addition screen to create the app:
- Doc Base: javaforcf . This is the name of the physical directory that serves as the root of this application.
- Path : /javaforcf . This is the name of the path that will be called in the browser to reference this Web application. So, to call documents in our test directory, we type this address: http://localhost:8080/javaforcf/filename.jsp . Note that JSP file names are case sensitive, because Java is.
- Working Directory: work\Standalone\localhost\javaforcf . This is the path name of the temporary directory that will store the Java class files that are generated by the servlets that are generated by your JSPs. This is the code that will be created the first time a JSP is accessed, and then the classes will be executed after that.
- SessionID Initializer: org.apache.catalina.session.StandardManager . This is the fully qualified name of the Java class the container will use to initialize sessions.

Figure 13.2. Tomcat Web Administration tool.

graphics/13fig02.jpg

Once you have entered these values, click Save and Commit Changes. Your context will be created. We now need to create the physical directory we referenced in creating this Web application.

13.6.2 Create the Web Application Directory

This is the directory that will hold all of our files for this Web application. Just like ColdFusion and IIS use wwwroot as the home base for the files they serve, Tomcat has a home base too. This is the Webapps directory, located under your <TOMCAT_HOME> root. In this folder, create a folder called javaforcf (since that is the name Tomcat will look for, as it corresponds with what we entered in the Administrator application).

There is a particular directory structure that Tomcat requires to hold the components of a Web application. Generally, the first step in creating an application is to create this directory structure. You create this directory structure in the Tomcat webapps directory; see Table 13.1 to see what it looks like.

Table 13.1. Tomcat Directory Structure

Directory	Purpose
`/javaforcf`	This is the root directory of the application. All JSP and HTML files should be in this directory. Create subdirectories as you see fit to organize your site; that is, you probably put graphics in a folder called "images" or style sheets in a folder called "styles."
`/javaforcf/WEB-INF`	Contains the Web Deployment Descriptor, an XML file that contains information about the different resources that make up the application, where they can be found, and how they are structured. This directory often contains Java classes and `.jar` files, as nothing in this directory or any subdirectory can be accessed directly by a client.
`/javaforcf/WEB-INF/classes`	Servlets and utility classes go here.
`/javaforcf/WEB-INF/lib`	Contains `.jar` files that the Web application requires. For example, you would put a JDBC driver, a custom tag library, an XSL transformer, or other extensions, here.

13.6.2.1 `WEB-INF`

Next, you need to create another folder to hold the Java classes you write and use in this application. Tomcat expects this folder to be called WEB-INF . Developers will often create folders underneath this folder that contain the packages with any Java classes they might use under this directory. That's because this directory is not accessible directly from the Web. That protects your classes and other resources from errant viewing by site visitors .

13.6.2.2 `web.xml`

Next, you need to create the application's deployment descriptor. This file, called web.xml , describes information regarding the configuration of the application. It can contain the following elements:

Servlet definitions
Servlet initialization parameters
Session configuration parameters
Servlet/JSP mappings
MIME type mappings
Security configuration parameters
An ordered list of welcome files
A list of error pages
Variable definitions regarding tag libraries and other resources, and environment variables

We will see how to use many of these elements in web.xml . Even if your application uses no servlets, tag libraries, or other resources, you still must create one.

The most minimal web.xml file looks like this:

 <?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> </web-app>

We can use this for now until we start adding elements, which we'll do along the way. There are a couple of things to be aware of regarding deployment at this point:

You do not need to do anything special once you have created a .jsp file to use in your application. Simply place it in the application and call it in a browser. This is contrary to the behavior of servlets, each of which must be explicitly accounted for in the deployment descriptor.
You can modify a JSP and reload it in the browser without having to restart the server. This is similar to ColdFusion.
Be careful to get the syntax absolutely correct in the web.xml file. Minor textual errors in this file can prevent Tomcat from starting. An easy way to make sure that your XML file is well- formed is to open it in Internet Explorer. Its built-in style sheet will display the page using its internal style sheet if everything is syntactically valid. If there is an error, the browser will notify you of it.
If you modify web.xml , you must restart Tomcat for changes to take effect. This is different from JRun 4, which now has "hot deployment."

To test our new Java Web application, we need to put a JSP into it. Take the test.jsp file that we called from ColdFusion MX earlier and place it into the <TOMCAT_HOME>/webapps/javaforcf directory. Open a browser and type http://localhost:8080/javaforcf/test.jsp . You should see:

 Hello, Eben!

If you get a 404 message, it generally means one of two things: you may have clicked the Save button, but not the Commit Changes button, when creating the application. Or, you may not have restarted Tomcat. These both mean that Tomcat does not know about your application.

Top