Laurie Williams, Ben Smith and Sarah Smith [Contact Authors]
CSC 326 - Software Engineering
Department of Computer Science
North Carolina State University

Back to Software Engineering Tutorials

A web-based application, or web application is is an application that's "accessed with a web browser over a network such as the Internet or an intranet" (Wikipedia).

Most webapps are deployed using a web application framework, and frequently entail the use of a database engine. This tutorial focuses on the Java application framework within Eclipse. Using the Java SDK, Tomcat, MySQL and the Sysdeo Plugin, we can deploy an application which:

• Is accessible from most web browsers.
• Contains dynamically generated content.
• Allows role-based access to data with various levels of sensitivity.

This tutorial will detail the basic steps to getting the software packages mentioned installed and configured on your home machine.

Apache Tomcat (download) is a program which acts as a container for Java Server pages and provides for their cooperation with a webserver. By following the download link above, you can select an installer or distribution package appropriate for your OS.

Before installing Apache Tomcat on your machine, please ensure that you have the JDK installed. The JDK is different than the JRE; the JDK provides the executables required to compile Java applications from source, whereas the JRE only contains the files needed to run Java bytecode.

2.1 Running Tomcat/Starting the Catalina Service

• To start/restart the Catalina service on a Macintosh computer, see this article
• To start/restart the Catalina service on a Linux computer, check out this aritcle
• Windows Users can execute the following steps:
1. Open Start Menu -> Programs -> Apache Tomcat 5.0 -> Monitor Apache.
2. A taskbar icon will appear, right click it and select "Configure."
3. Choose to either Start or Stop the service.

2.2 Setting up Administrator Access

You will need to have administrator access to the server. This is either accomplished through a Setup Wizard or by editing the XML configuration files directly. Be sure to note any administrator login pair you create for the server if you are using a wizard. If you need to add administrator access manually, complete the following steps:

1. Open the file (TOMCAT DIRECTORY)\tomcat-users.xml in your favorite text editor.
2. Add the following line to the XML file, where adminname is the admin username you'd like to use and adminpass is the password,:

   
   <user username="adminname" password="adminpass" roles="admin,manager"/> 
   

   This line can be placed anywhere in the file.
3. Save the file and restart the Catalina service.

2.3 Configuration Manager Access

Either when you are installing Tomcat (through a wizard) or by configuring it manually, you need to add manager access for the Sysdeo plugin. If you are installing via a wizard, just be sure to select the option to create a manager account and remember the username/password combination you create. For adding a new manager user, execute the following steps if you have admin access:

1. Open your favorite browser and point it to http://localhost:8080/admin. You will be asked to Login. Provide your Administrator access information from section 2.2 or otherwise.
2. A frameset page will appear. On the menu on the left side of the page, select "Users" under "User Definition."
3. Click the dropdown combobox on the right side of the screen that says "User Actions," and select Create New User.
4. Fill in the appropriate username and password pair that you will record and have ready for the Sysdeo configuration later.
5. Be sure to check the checkbox under the column "role name" that says "manager."
6. Click Save. Click the "Logout" button at the top-right side of the window.

2.4 Using the Tomcat Manager

After configuring a user with manager status for the deployment of applications, you can access the manager application to deploy applications if you wish. If you are trying to use the Sysdeo plugin, skip this step.

To configure an application manually:

1. If you have Tomcat running, open your favorite browser and point it to http://localhost:8080/manager/html.
2. You will have to login using Browser Authentication and a username/password pair you created for Manager access.
3. After logging in, you will see that you can start, stop and reload all applications from this portal. To deploy a new application, fill out the forms in the Deploy table. They have the following meanings. If you have Tomcat running, you can see the HTML Manager Help page for more information.
• Context Path: This is the path a web user types in to access the application. It can differ substantial from the actual location of the project on the system.
• XML Configuration File URL: A relative path to the XML file which can contain application-specific directives to the server.
• WAR or Directory URL: A WAR is similar to a JAR, but you have the option of only entering a path on the filesystem.

2.5 WINDOWS USERS READ THIS

For some indeterminate reason, Tomcat cannot compile JSPs on a Windows machine without a key JAR file. Before attempting to run your first Tomcat application, copy JAVA-HOME\lib\tools.jar to TOMCAT-HOME\common\lib.

The rest of this tutorial focuses on deploying Tomcat applications from within the Sysdeo plugin (below). For more information on how to configure Tomcat, please refer to the online documentation.

The Sysdeo Plugin is an Eclipse plugin that runs Apache Tomcat from within a user's workspace. We use this plugin because it allows error messages created by the JSPs to be printed to the console (as opposed to a log file), because it automatically deploys projects to the local Tomcat server and just generally facilitates integration of Eclipse and Tomcat.

The Sysdeo Plugin will have to be manually installed. For more information on manually installing plugins, please refer to the Installing Eclipse Plugins tutorial. You will know you have the plugin correctly loaded into the Eclipse Environment when the Tomcat buttons appear next to the run button. They look like this:

IMPORTANT: Though it may be tempting, DO NOT click start button until you have properly configured the Sysdeo plugin. Also do not attempt to start Tomcat from within Eclipse while the Catalina service is already running. Check the status of your Catalina service and then proceed.

3.1 Configuring the Sysdeo Plugin to work with the Eclipse IDE

Figure 3.1

After the Sysdeo Plugin is installed, you will need to initialize it by telling it where Tomcat is, etc, by taking the following steps:

1. From within an Eclipse workspace, click Window -> Preferences...
2. Click the expand button next to the Tomcat set of options.
3. From the main preferences applet, make sure your Tomcat version is set to 5.x, and that your Tomcat home is pointed to the correct installation directory. Click Apply. NOTE: The Tomcat Home directory is not any subdirectory of the Tomcat installation.
4. Click the Advanced tab. Point Tomcat base to the same directory as you did Tomcat home. Click Apply.
5. Click the Tomcat Manager App tab. Make sure the Tomcat ManagerApp URL points to http://localhost:8080/manager/. Click Apply.
6. Fill in a username and password for a user setup with manager access. This could be the one you created in section 2.2. Click Apply.
7. Click OK at the bottom of the preferences window. See Figure 3.1 above for reference.

The Sysdeo Tomcat plugin is now installed, however your project is not deployed yet. To create and deploy your first project, see the next section.

3.2 Converting your Project to a Web Application

Figure 3.2a

There are several different ways you could set up a project to deploy it as a web application, but the following is the most straightforward and easiest. There are certain folders and files that you will need inside the project for it to function correctly as a webapp, especially for your JSPs to have access to any Java classes you may design on your own. You will start with a structure similar to that in Figure 3.2a. To prepare your project's structure for deployment:

1. Using Eclipse, create a folder in the root of the project called webapp/. This is where your JSPs will go.
2. Using Eclipse, create a folder underneath /webapp called WEB-INF/. This is a folder for Tomcat that dictates configuration.
3. Download the file web.xml to your webapp/WEB-INF/ directory. This will tell Tomcat that you want to make this application a Servlet.
4. Using Eclipse, create a folder underneath /webapp/WEB-INF/ called classes/ This is where all your Java Bytecode files will end up.
5. Right-Click on the project, Select Properties, and on the window that appears, select the section "Java Build Path".
6. Click the "Browse" button next to the textbox for "Default output folder." Select the folder /webapp/WEB-INF/classes
7. Eclipse will ask you if you want to remove all the old resources. To keep your project clean and easy to navigate, click "Yes" and then after it has completed the operation, find the folder /bin and delete it. NOTE: the /classes folder will disappear once you have set it as the output folder. Eclipse always hides output folders to avoid confusion.
8. Your project is now ready to be deployed. After completing these steps, your structure should look like Figure 3.2b.

Figure 3.2b

3.3 Deploying a Tomcat Project

Figure 3.3a

Now that you have Tomcat and Sysdeo installed, you can easily configure web applications from within Eclipse. Assuming you have a project created, Sysdeo inserts the proper configuration statements into the XML of the configuration file and the application is deployed. To deploy your application on the local Tomcat machine:

1. Right click on the project, select Properties, and on the window that appears, select the "Tomcat" section. See Figure 3.3a above for reference.
2. Make sure the checkbox "Is a Tomcat Project" is checked.
3. Set the context name. If you want to access your application from the address http://localhost:8080/myapp/, for instance, the context name would be /myapp.
4. Be sure to set the "subdirectory to set as web application root" to the /webapp folder you created in the previous section. You do not need to modify any of the other tabs in this panel.
5. Click Apply. Click OK to close the Properties Window.
6. Right click on the project again, except this time go to the menu "Tomcat Project."
7. Click "Add Tomcat Libraries to project build path."
8. Repeat the process, except this time click "Create JSP work directory." The Sysdeo plugin will automatically create a sourcefolder for the work directory, which will contain your compiled JSPs.
9. Repeat the process again, except this time click "Update Context Definition."
10. Congratulations, your project has been deployed. You will need an index.jsp to really see it work, create your own or just download this one (right click, save as) to your /webapp directory.
11. Start the Tomcat Server from within Eclipse by clicking the icon. Go to http://localhost:8080/your_app_name_here/ to see it in action. Your project should now look like Figure 3.3b.

Figure 3.3b

For more information on JSPs and Servlets, check out the The JSP Module on Open Seminar.

3.4 Debugging Your Webapplication

Any time that Tomcat is running using the Sysdeo plugin and your application is running through Eclipse, you can debug your application just as you would any other Java Application. The sourecode of the classes you create can be marked with a breakpoint, and monitored in depth from the Debug Perspective. For more information on loading the Debug Perspective, see the Eclipse Tutorial, Section 5.

4.1 Installing MySQL

The MySQL database server is available for download for free from MySQL AB, the program's provider. The entire list of package downloads is available here. In order to begin creating databases and executing SQL queries, you will need to provide yourself root access to the MySQL server. You will want to create a user with minimal privilages (insert, update, select, delete) priviledges on the database and/or tables that your web application will be using. This is to reduce the chance of getting hacked. The Reference Manual, Chapter 2 has more information regarding platform-specific installation and configuration options. Windows users be sure to start the service for the MySQL daemon before attempting to configure it.

4.2 Setting up Databases with MySQL

You will not want to hardcode the SQL queries to create a database into your Java programs; the database should be predetermined and hardcoded, to prevent database hacks such as a SQL Injection (Wikipedia). To create a database on your server, after it is configured and you have root access, see the MySQL tutorial on database use. You may also want to install MySQL Administrator, a GUI configuration tool for your server.

4.3 Installing the MySQL Connector

The MySQL connector (download) is a Java library that allows a set of classes to quickly execute and manage MySQL queries. To use it with your project, follow these steps:

1. Download the ZIP file to a location where you can find it and then proceed to unzip it.
2. Copy the file mysql-connector-java-3.1.10-bin.jar to your project's /lib directory. If you do not have a /lib directory, we suggest you create a /lib directory and copy the JAR there..
3. Right-Click the project, Click Build Path -> Configure Build Path...
4. Click "Add JARs..." and find the mysql-connector-java.jar file. Click OK.
5. For any class or .java file that needs to use the MySQL connector, be sure to include the statement import java.sql.*; in the import section of the source so that you can access Connection, Statement and Resultset as classes.

4.4 Using the MySQL Connector

The MySQL Connector library creates a huge set of Java classes for everything in the SQL environment. For more information on using the MySQL connector in depth, please see The Java Tutorial on this subject. The main classes that we are concerned with for rudimentary input and output on the database are provided with the Java libraries in the SQL package:

• Driver: This is a static class in the package com.mysql.jdbc.* which instantiates connections to the MySQL server. For use, see the example code below.
• Connection: This is a class that contains one instance of a live connection with a server.
• Statement: Executes all statements, queries or updates and also allows for parsing of strings into SQL statements.
• ResultSet: A container of every row or column data that you have retrieved if you execute a query.

Since the MySQL Connector is meant to be extremely flexible and extensible, understanding each class can be daunting. SQLConnection.java contains methods which perform the tasks of creating and working on a JDBC connection. We have also included the following example, which when run will print the first user listed in the user's table of your MySQL server. This example makes use of the SQLConnection.java class.

import java.sql.*;


try
{
	SQLConnection cn = new SQLConnection();
	Statement stmt = cn.getStatement();
	ResultSet rs = stmt.executeQuery("SELECT * FROM `user`;");
	if (rs.next())
		System.out.println(rs.getString("User"));
	
	cn.closeConn();
}
catch (Exception E)
{
	System.out.println(E.toString());
}