Web Application Overview

Revised: November 16, 2004

Important: The Java application server and MySQL database are not included as part of the kinetic Service annual fee. These technologies are available on an as-requested basis for an additional fee. Contact David Drum at david@more.net or (800) 509-6673 for additional information.

Contents

• Overview
• Managing Your Web Application
• Web Application Directory Structure
• Web.xml -- Web Application Deployment Descriptor

Overview

A Java web application is a collection of resources that function together as a complete application to perform some web-based service. These resources may include:

• Static files (HTML, images, sounds, etc.)
• JavaServer Pages
• Custom JSP tag libraries
• Java Servlets
• Java classes
• Archived Java libraries (JAR files)
• Configuration information that ties all of the resources together (Java properties files, web.xml)

A Java web application is typically bundled or packaged into a Web Application Archive .war file for distribution. An installation program isn't needed for a web application because the application resources and its directory structure is inherently stored in the .war file, similar to how a .zip file can store archived files and maintain their original directory structure. The actual format of a .war file isn't special — it is a Java Archive (.jar) file that was created with the Java SDK's Jar tool and saved with a .war filename extension.

Managing Your Web Application

The Tomcat Manager provides the ability to install, start, stop, reload, and remove your web applications. You may use the Tomcat Manager from any location with a web browser to manage your web applications.

Overview

A Tomcat Manager exists for the primary (#1), failover (#2), and spare (#3) application servers (the roles of these servers are described in the Java Application Server Overview document). To visit each Tomcat Manager, type the appropriate URL in your web browser and replace {webdomain} with your website's domain name. Note that the numeral in the URL indicates the server as indicated above.

• http://{webdomain}/manager1/html/list
• http://{webdomain}/manager2/html/list
• http://{webdomain}/manager3/html/list

Important: You must manage your applications separately on each server since all three servers are configured to host your web applications. However, the spare server (#3) is not typically configured to accept requests unless there is a problem with the primary and failover servers, so its Tomcat Manager will not usually be available.

When you attempt to visit the Tomcat Manager, a window displays with options for a username and password. This authentication provides protection so that anonymous Internet users cannot access the Tomcat Manager. For more information about managing accounts that can access the Tomcat Manager, see Managing Tomcat Manager Usernames and Passwords. If you authenticate with the correct username and password, the Tomcat Manager displays the applications that are installed and their context paths, names, running status, and the number of active sessions.

Important: Once you successfully authenticate for the Tomcat Manager, you will not have to authenticate again until you close your web browser or exceed the 30 minute session timeout without interacting with the Tomcat Manager. When you are finished with the Tomcat Manager, it is best to close your web browser. This is especially important if you are using the Tomcat Manager from a shared computer.

Upon successful authentication, the Tomcat Manager lists all of the web applications that you've installed with links to perform the following actions:

• Start. Click Start to make your application available for requests if you have previously stopped it.
• Stop. Click Stop to make an application stop processing. This is valuable if there is a problem with your application and you need to make it unavailable until you can fix the problem.
• Reload. Click Reload to force Tomcat to reload your application. Sometimes you may make changes to your application that require a reload for the changes to take effect, such as changes to the class files or libraries. Note that changes to the web.xml file require a stop/start of the application.
• Remove. Click Remove to instruct Tomcat to gracefully shut down the application and remove the context path. Be careful with this command! It removes the directory structure that was created when you installed your web application.

The Tomcat Web Application Manager How To document on the Jakarta web site provides additional details about using the Tomcat Manager.

Managing Tomcat Manager Usernames and Passwords

The Tomcat Manager uses realm-based authentication with a MySQL database. The database administrator for your organization may add, remove, and update Tomcat Manager accounts within the database.

Tomcat is configured like the local development environment as documented in the Installing the Tomcat Java Application Server document. To review how to manage Tomcat Manager usernames and passwords, see the Configuring and Using the Tomcat Manager section of that document.

Important: Unlike the local development environment, the customer MySQL server does NOT contain a local_realm database. For easy identification, the name of each kinetic Service customer database uses a prefix that matches the customer's web site domain name. Hence, the database for Tomcat Manager accounts is named {webdomain}_realm, where you replace {webdomain} with your web site domain. Note that since the '.' character is reserved in MySQL, all '.' characters are replaced with '_' characters in the domain name (i.e., exampledomain_k12_mo_us_realm).

Installing and Starting a Web Application

Servlet containers such as Tomcat understand that a .war file is an application and they have facilities for installing an application from a .war file. To install an application in Tomcat, follow these steps:

Important: Upon a successful installation, Tomcat will automatically start your web application. For more information about stopping and starting applications that are already installed, see Stopping and Starting Your Web Application.

1. Visit the Tomcat Manager for the failover server (#2) at the URL below. Note that you must replace {your-domain-name} with the domain name of your web site:
   
   http://{webdomain}/manager2/html/list
   
   If you authenticate with the correct username and password, the Tomcat Manager displays the applications that are installed and their context paths, names, running status, and the number of active sessions.
2. In the Upload a WAR file to install section, click Browse, select your web application .war file, and then click Open (or whatever button your browser displays to proceed).
3. Click Install to upload and start your web application on the failover server. If the upload succeeds, the Message box at the top of the Manager displays "OK - Installed application at context path /context-path" and your application displays in the list of applications.
   
   If the Tomcat Manager reports an error, make a note of the error and then click the HTML Manager Help link in the Manager section. The Tomcat Manager documentation provides more information about common errors.
   
   The contents of the .war file is extracted into a subdirectory of the /www directory of your web site, and it is given the same name as the .war file without the filename extension. This name also matches the Context Path for your application as displayed in the Tomcat Manager. You can view this directory structure with an FTP client just like the rest of your kinetic service web site.

   Important: At this point you have installed the application on the failover server. Under normal circumstances, you will not be able to visit the application until you install it on the primary server.

4. Visit the Tomcat Manager for the primary server (#1) at the URL below. Note that you must replace {your-domain-name} with the domain name of your web site:
   
   http://{webdomain}/manager1/html/list
   
   
5. In the Install directory or WAR file located on server section, instruct the Tomcat Manager to install the application from file.

   Note: This step varies from the installation on the failover server because the .war file is already unarchived. To install the application on the primary server, you must instruct the Tomcat Manager to install from the unarchived web application.

   In the WAR or Directory URL field, type file:{complete-path-to-webapp}, where you replace {complete-path-to-webapp} with the complete server path to the web application. If you are unsure what to type, use an FTP client to navigate to the web application directory created from your .war file in the previous step. Replace {complete-path-to-webapp} with the long path displayed for the 'Remote Site' within your FTP client.
   
   The value that you type will resemble the following. Note that this line was divided into two lines for readability.
   
   file:/export/kinetic/home/kinetic.more.net/ttt/eee/testact/WebPublish /web/mo/example/example.mo.gov/www/my-example-application
   
   
6. Click Install to install and start your web application on the primary server. If the installation succeeds, the Message box at the top of the Manager displays "OK - Installed application at context path /context-path" and your application displays in the list of applications.
   
   If the Tomcat Manager reports an error, verify that the path you specified is correct as reported by your FTP client.
   
   

Stopping and Starting Your Web Application

Circumstances occur when you must stop and start your web application with the Tomcat Manager. Stopping the application prevents it from running and being accessible with your web site. For example, it is common to stop your web application when it must be inaccessible for troubleshooting existing problems and when the web application must be updated with new source files. Follow these steps to stop your web application:

1. Visit the Tomcat Manager for the primary server (#1) at the URL below. Note that you must replace {your-domain-name} with the domain name of your web site:
   
   http://{webdomain}/manager1/html/list
   
   
2. Review the list of applications for the name of your web application and then click the Stop link that is located to its right.
3. Visit the Tomcat Manager for the failover server (#2) at the URL below. Note that you must replace {your-domain-name} with the domain name of your web site:
   
   http://{webdomain}/manager2/html/list
   
   
4. Review the list of applications for the name of your web application and then click the Stop link that is located to its right.

To start your web application, visit the Tomcat Manager for the primary server, click the Start link that is located to the right of your web application's name, and then repeat these steps for the failover server.

Note: The Start link is not available unless the web application is already stopped.

Removing Your Web Application

Circumstances occur when you must remove your web application with the Tomcat Manager. For example, it is common to remove your web application when you need to update it with a new .war file or to permanently remove the web application because it is no longer needed. Follow these steps to remove your web application:

Important: Be careful with the Tomcat Manager's remove command! It removes the directory structure that was created when you installed your web application.

1. Follow the steps in Stopping and Starting Your Web Application to stop your web application.
2. Visit the Tomcat Manager for the primary server (#1) at the URL below. Note that you must replace {your-domain-name} with the domain name of your web site:
   
   http://{webdomain}/manager1/html/list
   
   
3. Review the list of applications for the name of your web application and then click the Remove link that is located to its right.
4. Visit the Tomcat Manager for the failover server (#2) at the URL below. Note that you must replace {your-domain-name} with the domain name of your web site:
   
   http://{webdomain}/manager2/html/list
   
   
5. Review the list of applications for the name of your web application and then click the Remove link that is located to its right.

Updating Your Web Application

Up to three application servers can be using the files in a web application at the same time. Although the web application files exist in one web application directory, the use of three server requires special care when you update your web applications. Follow these tips to ensure that updates to your applications work properly:

• You may update JavaServer Pages (.jsp) without stopping the application. Use an FTP client to upload the files to the unarchived web application directory. After you have updated the .jsp files, the first visits to the pages will trigger the application servers to recompile them and serve the new versions.
• To update a .jar file, web.xml, or properties file, you must first stop the application using all three of the Tomcat Manager applications as described in Stopping and Starting Your Web Application (normally only two are running). Update the files using an FTP client and then start the web application in each application server with the Tomcat Manager applications.

  Caution: Failure to stop the web application in all running application servers prior to updating a .jar file, web.xml file, properties files, or installing a new .war file can result in one or more of the application servers failing.

• To replace the web application from a new .war file, you must first remove the application in all of the running application servers (under normal conditions, only the primary and failover servers are running). Follow the steps in Removing Your Web Application. After the application is removed from all servers, repeat the steps in the Installing and Starting a Web Application section to install the application from a new .war file.

Web Application Directory Structure

A web application exists in a servlet container as a hierarchy of directories. The root of the application directory may contain public documents and JavaServer Pages (JSPs). The application developer may place these files in other directories as well, such as organizing all of the graphic images into a /graphics directory or some other organization structure. Although most of the directory names in an application are up to the discretion of the developer, the /META-INF and /WEB-INF directories are inherent to all web applications.

The /META-INF directory contains information about the WAR file. This directory and its contents are created by the JAR tool when the WAR file is created and it is extracted when the WAR file is installed. You need not worry about this directory or its contents, such as the manifest.mf file that contains information about the WAR file. Like the contents of the /WEB-INF directory detailed below, the contents of the /META-INF directory are not public and cannot be served by the web server or application server.

The /WEB-INF directory contains all of the things related to the application that are not public and cannot be served by the web server or application server. The following subdirectories and files exist in this directory:

• /WEB-INF/web.xml -- the web application deployment descriptor (configuration information)
• /WEB-INF/*.tld -- tag library descriptor files
• /WEB-INF/lib/*.jar -- Java libraries, servlets, beans, tag libraries and other supporting Java classes packaged in JAR files
• /WEB-INF/classes/ -- Java classes and servlets needed to support the application
• /WEB-INF/classes/*.properties -- Java properties files need to support application

Web.xml -- Web Application Deployment Descriptor

Use the web.xml deployment descriptor file to configure a web application. The Tomcat servlet container reads this file when it loads your web application. It is an XML document which uses predefined tags from a rule set.

Note: The document XML in 10 points highlights the premises of XML.

An XML tag has the following format:

<element attribute1="value1" attribute2="value2" ...>

</element>

If you have hand-coded HTML, this may look familiar. However, unlike HTML, XML tag syntax is strictly enforced. Every opening tag must be closed by a corresponding closing tag (< /element>) or it must be self-closed with /> at the end of the tag. Unlike HTML, XML is case-sensitive. Another obvious differentiation with HTML is that XML documents must contain an XML declaration as the first tag on the page. An example is shown later in this document.

One of the useful things about XML is that you can specify a rule set in another document for validating the XML. This rule set document is called the Document Type Definition (DTD). A DTD is not mandatory for every XML document. However, it is mandatory to verify that an XML document is valid (i.e., adheres to a rule set). This is particularly important when XML documents contain data that must be shared between disparate systems, and the systems must agree on a format for the data. This applies to web.xml since it is validated by a servlet container and thus it has a DTD.

Although the finer details of DTD construction are too vast to document here, you should understand a few basic concepts before you dive into authoring a web.xml file for an application. You may frequently refer to the web application deployment descriptor DTD; understanding its structure will help. Three key concepts include:

• The DTD defines the elements that are valid and the types of data they may contain. The elements in the DTD map directly to the tags that may appear in an XML document that references the DTD.
• The DTD defines the structure of the XML document and how the elements relate to each other. For example, the DTD defines whether an element may or may not have attributes, which elements have children (i.e., XML tags that must exist inside other tags), and how many instances of a tag can appear in the XML document.
• The DTD, like an XML document that references it, is case-sensitive.

Web.xml Specifics

As shown below, every web.xml must have the following header information that identifies it as an XML document and details the location of the DTD. The DTD location is specifically referenced in the Java Servlet Specification Version 2.3 from Sun.

<?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">

For a complete reference to the web.xml DTD, please refer to the web-app_2_3.dtd on Sun's web site. This DTD is also described in the Java Servlet Specification. You'll find many descriptive comments in the DTD since it contains comments in the form of <!-- comment --> just like standard HTML.

Within the DTD you'll see the following declaration:

<!ELEMENT web-app (icon?, display-name?, description?, distributable?,
context-param*, servlet*, servlet-mapping*, session-config?,
mime-mapping*, welcome-file-list?, error-page*, taglib*,
resource-ref*, security-constraint*, login-config?, security-role*,
env-entry*, ejb-ref*)>

As mentioned earlier, the DTD defines the valid elements and the structure of the XML documents that reference the DTD. Three important concepts are related by the above declaration:

• web-app is the root element and it has many children elements, such as icon and display-name. As the root element, the <web-app> tag must enclose all of the other tags in your web.xml (other than the XML declaration and the DOCTYPE definition at the top of the document). The children are defined later in the DTD.
• The order of the child elements define the order in which they must appear in the XML document. For example, <display-name> cannot appear before <icon>.
• All of the child elements that are followed by a question mark indicate that the elements can be declared zero or one times. For example, <icon> can only be declared once, if declared at all.
• All of the child elements that are followed by an asterisk indicate that the elements may be declared zero or more times. For example, you could define <servlet-mapping> many times in your web.xml.

Some of the most common elements used for configuring a web application are detailed in the sections below.

Important: Remember that the relative order of the elements is important. Also, the examples below include "..." to denote that other elements may exist above and below the example code. Do not place these in your final configuration files.

<web-app>

<web-app> is the root element. All of the other elements that configure your web application are nested within the opening <web-app> and closing </web-app> tags.

<display-name>

Use the <display-name> tag to provide the name of the web application. Only one <display-name> tag should exist as an element within the <web-app> parent element. This element is used by the Tomcat application manager as the name of the application.

<web-app>
...
  <display-name>
    infoRequests
  </display-name>
...
</web-app>

<description>

Use the <description> tag to provide descriptive text about the web application. Only one <description> tag should exist as an element within the <web-app> parent element.

<web-app>
...
  <description>
    Guest registration application.
  </description>
...
</web-app>

<welcome-file-list> and <welcome-file>

Use the <welcome-file-list> element to specify one or more of the application's files that should be displayed when a URL requested by an end user only indicates a directory. Each file is specified in a <welcome-file> element, and the <welcome-file-list> is the parent element for all of the <welcome-file> elements. The order of the <welcome-file> elements makes a difference — the servlet container searches the requested directory for the welcome files from first to last and stops when it finds one of the files.

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

Important: These elements are not especially useful on a production server. The Apache web server determines if HTTP requests should be handled by it or Tomcat, and it only forwards requests to Tomcat for .jsp files, servlets (the URI contains /servlet), and Struts .do files. HTTP requests that only indicate a directory are not forwarded to Tomcat. To ensure that requests that only specify a directory are properly forwarded to Tomcat, you can add an index.shtml file in the root of your web application. In this file, use Apache's Server-Side Include (SSI) statement to include the .jsp or servlet that you want to invoke for your application. Apache will process the SSI due to the .shtml file extension and then include the appropriate file from your web application. For example, the following examples use SSI to include a .jsp and a servlet:

<!--#include virtual="/card-catalog/index.jsp" -->

<!--#include virtual="/card-catalog/servlet/Search" -->

<session-config> and <session-timeout>

Use the <session-config> element to specify the session timeout value for all sessions created in this web application. If the session does not have any activity for this time, it is considered an expired session. <session-config> is the parent element of and requires the <session-timeout> subelement. The timeout value must be expressed as an integer in minutes, such as the 10 minute timeout in the example below.

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

<error-page>, <error-code>, <exception-type>, and <location>

Use the <error-page> element to map one or more resources in the web application to an error code or exception type. This functionality is similar to the error page ability provided by the JSP page directive, but allows finer control. <error-page> is a parent element to the <error-code>, <exception-type>, and <location> elements; each <error-page> element must contain the <location> element and either an <error-code> or <exception-type> element. The <error-code> contains an HTTP error code, such as 404. The <exception-type> contains a fully qualified class name of a Java exception type. The <location> element defines the resource, such as a JSP, that is displayed when the corresponding error occurs.

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

<%@ taglib uri="/WEB-INF/scrape.tld" prefix="scrp" %>

<%@ taglib uri="/scrapeTags" prefix="scrp" %>