Tomcat Installation and Servlet Deployment

This is a short introduction to help you set up Tomcat and deploy Java servlets. For more information, please refer to Apache Tomcat.

(Please tell me if you find any errors or omissions in the document —Upsorn Praphamontripong, 11-January-2018)

Getting Started With Tomcat

If you do not alreaady have Java on your machine, download and install Java Development Kit. Note: You should verify which JDK version is supported by the version of Tomcat you are using.
- Download Java EE from http://java.sun.com/
- Install JDK and JRE according to the instructions included with the release.
- Set the environment variable JAVA_HOME to the directory where you installed the JDK release:
  - for Window
  - for Mac
- You may need to restart your computer.
Download Tomcat "Core" zip file from: http://tomcat.apache.org/.
Unzip the apache-tomcat zip file
- (for Window) Assuming you unzipped it on drive C, the path is C:\apache-tomcat
- (for Mac) Assuming you unzipped it in Applications folder, the path is Applications/apache-tomcat
Startup Tomcat
- (for Window)
  - Double click C:\apache-tomcat\bin\startup.bat, or
  - Use a terminal, go to C:\apache-tomcat\bin\ then execute startup.bat
- (for Mac)
  - Use a terminal, go to Applications/apache-tomcat/bin/ then execute ./startup.sh
After startup, the default web applications included with Tomcat will be available by browsing http://localhost:8080/
Shutdown tomcat
- (for Window)
  - Double click C:\apache-tomcat\bin\shutdown.bat, or
  - Use a terminal, go to C:\apache-tomcat\bin\ then execute shutdown.bat
- (for Mac)
  - Use a terminal, go to Applications/apache-tomcat/bin/ then execute ./shutdown.sh

Setup Tomcat in Eclipse environment

Note: This is optional. You may use any IDEs of your choice with tomcat installation from the previous step.

Requirements: Tomcat, Eclipse, JDK, and JRE

Open Eclipse
Go to the Servers tab.

If the Servers tab does not appear on the screen, open the view using menu bar Window > Show View > Servers
Under the Servers tab, right click and select New > Server
Select the version of your Tomcat. You may use the default server name or change it. Then click Finish
Once the server is setup, to start the server, right click on the server name, then select Start

Note: When you right click on the servlet .java file and select Run As > Run on Server, Eclipse will prompt a window to start the server. You can also choose to have the server starts automatically as you run the servlet.
To stop the server, right click on the server name, then select Stop

An alternative way to set up Tomcat in Eclipse is to specify a target runtime when creating a new dynamic web project. (Thanks to Yuchi Tian)

Working with Java Servlet

Create a Java servlet (.java file)

You may use any IDEs that support Java web develoment such as Eclipse WTP, IntelliJ, and NetBeans.
Some IDEs automatically include a path to servlet-api.jar while some require that you set class path to servlet-api.jar
For Eclipse user
- Create a dynamic web project (depending on the version of your Eclipse) by selecting Create a new Java EE Web Project or using the menu bar File > New > Dynamic Web Project
- Enter your project name (let's keep default configuration), then click Next and Next to configure Web Module. Note: You may choose to click Finish and generate web.xml to configure Web Module later.
  
  On the Web Module window, select Generate web.xml deployment descriptor. Note: If you choose to manually create web.xml later, you may leave the checkbox blank.
- Under your newly created project, open Java Resources, right click on the src folder, select New > Servlet to create a new Java servlet (.java file).
  
  Enter the name of your servlet in Class name. If you choose to have a package for your servlets, you may enter the package name in Java package.
  
  Note: If you prefer to create a package before creating a servlet, instead of selecting New > Servlet (above), select New > Package to create a package. Then, right click on the newly created package, select New > Servlet to create a servlet.
  
  Open the newly create servlet, if there are errors (for example, as shown in the following figure), you need to add servlet-api.jar to your project.
- To add servlet-api.jar to your project
  - Open Project Properties by
    - Right click on the project name and then Properties, or
    - Use a menu bar Project > Properties
  - Select Java Build Path
  - Select Libraries tab
  - Press Add External JARs... button
  - Navigate to the location where you save servlet-api.jar. Note: By default, servlet-api.jar is part of Apache Tomcat and is usually in
    - (for Window) C:\apache-tomcat\lib
    - (for Mac) Applications/apache-tomcat/lib
  - Select servlet-api.jar
  - Press Open button.
    - servlet-api.jar should appear under JARs and class folders on the build path panel

Write code / implement your servlet

Implement a doGet() method as needed
Implement a doPost() method as needed
Implement additional Java functions as needed

Compile a servlet. A Java servlet is a .java file and thus must be compiled before it can be run.

For Eclipse user, when you run a servlet (right click on the servlet .java file and select Run as > Run on Server), Eclipse automatically compiles the file before running it.
To manually compile a Java servlet, you may need to set a classpath to include servlet-api.jar (presumably in apache-tomcat/lib/ folder).
- You may set a classpath via your computer configuration
  - This usually involves opening the Control Panel > System > Advanced > Environment Variables.
- You may set the path while compiling the servlet Java file (using a command line). For example,
  - (for Window)
    javac -cp "C:\Applications\apache-tomcat\lib\servlet-api.jar" servlet-name.java
  - (for Mac)
    javac -classpath "/Applications/apache-tomcat/lib/servlet-api.jar" servlet-name.java
  Note: The syntax may be different depending on your computer configuration. Based on CS4640-S17 students, the above Mac-syntax worked for some Mac users but not for some; similarly, the above Window-syntax worked for some Window users but not for some. Please let me know if you have any suggestion on syntax (either for Mac or for Window).
If your servlet is in a package, when compiling with javac, you need to compile the servlet from "above" the directory:
For example, javac package-name/Hello.java (assuming servlet-api.jar has already been included in the classpath)

Map servlet

Every Java servlet needs a servlet mapping. There are two options. (Note: use either one of these options)

Option 1: Use a servlet.annotation.WebServlet
- Import a servlet.annotation.WebServlet to your Java file by including the following line
  import javax.servlet.annotation.WebServlet;
- Then, include the following line before a class declaration
  @WebServlet("/your-servlet-name")

Option 2: Use a web.xml file

If you do not use Tomcat in Eclipse environment, create a default web.xml file under your project directory (so-called "context") in apache-tomcat folder. Then, add the <servlet> and <servlet-mapping> tags to web.xml file.

(for Window)
C:\apache-tomcat\your-project-name\WEB-INF\web.xml
(for Mac)
Applications/apache-tomcat/your-project-name/WEB-INF/web.xml

  <?xml version="1.0" encoding="UTF-8"?>
  <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
    <servlet>
      <servlet-name>YourServletName</servlet-name>
      <servlet-class>YourServletClass</servlet-class>
    </servlet>
    <servlet-mapping>
      <servlet-name>YourServletName</servlet-name>
      <url-pattern>/YourURLMapping</url-pattern>
    </servlet-mapping>
  </web-app>

cs4640

HelloServlet.java

HelloServlet.class

  <?xml version="1.0" encoding="UTF-8"?>
  <web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
    <servlet>
      <servlet-name>Hello</servlet-name>
      <servlet-class>HelloServlet</servlet-class>
    </servlet>
    <servlet-mapping>
      <servlet-name>Hello</servlet-name>
      <url-pattern>/Hello</url-pattern>
    </servlet-mapping>
  </web-app>

http://localhost:8080/cs4640/Hello

QAselector

jeopardy

     <servlet> 
       <servlet-name>QAselector</servlet-name> 
       <servlet-class>jeopardy.QAselector</servlet-class>         
     </servlet> 
     <servlet-mapping> 
       <servlet-name>QAselector</servlet-name> 
       <url-pattern>/QAselector</url-pattern>  
     </servlet-mapping>

http://localhost:8080/cs4640/QAselector

     <servlet>
       <servlet-name>QAselector</servlet-name> 
       <servlet-class>jeopardy.QAselector</servlet-class>         
     </servlet> 
     <servlet-mapping> 
       <servlet-name>QAselector</servlet-name> 
       <url-pattern>/jeopardy.QAselector</url-pattern>  
     </servlet-mapping>

http://localhost:8080/cs4640/jeopardy.QAselector

Deploy a servlet. The server can accept many different formats, including .war and .class. The rest of these instructions assume you are deploying a simple .class file.

To deploy your servlet, follow these steps:

(for Window) Go to C:\apache-tomcat\webapps
(for Mac) Go to Applications/apache-tomcat/webapps

You might need to create a project directory ("context") under webapps folder. Assume you give your project name as cs4640:

Directory	Contains
`\cs4640`	This is the root directory of the web application. All JSP and HTML files are stored here.
`\cs4640\WEB-INF\classes`	This directory is where servlet and utility classes are located.
`\cs4640\WEB-INF`	This directory 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 contained in this directory can be served directly to a client.
`\cs4640\WEB-INF\lib`	This directory contains Java Archive (JAR) files that the web application depends upon. For example, this is where you would place a JAR file that contains a JDBC driver.

Copy your class files to the classes directory. Note that when you replace a class in the classes directory, the files do not get reloaded dynamically. You must restart the server (shutdown tomcat, start it again).
Note: In reality, if you use a shared server, do not put your .java source files in the public directory!

Setting permission. Make sure that your files are readable and executable

Go to apache-tomcat/webapps/project-name/WEB-INF/classes/package-name
Run a command chmod 755 *

Running / accessing a servlet

To access via a web browser
- Enter a URL similar to http://localhost:8080/project-name/servlet-name
To access through Eclipse
- Right click on the Java servlet name (.java file), select Run As > Run on Server. Eclipse will access the servlet using a virtual browser.

Additional Notes

Tomcat keeps its log files in the director apache-tomcat/logs/. The files catalina.out and local_access_log.2018-MM-DD.txt accumulate log entries from Tomcat (MM is a 2-digit indicator of the month and DD is a 2-digit indicator of the day). You can look here to find error messages from your servlets.
Caution!!
Never ever do this, especially if you use a shared server:
```
      try
      {
         ... ...
      } catch (Exception e) {
         System.out.println(e.getMessage());
         System.exit(0); 
      }
```
The servlet is running inside Tomcat.
System.exit(0); will cause Tomcat to exit. Everyone who shares the server with you will be very angry!