CPSC 371 Lab, 5 September 2003
Getting Started with Tomcat

The purpose of the lab today is to make sure that you have the Tomcat server up and running correctly, either on your own computer or on one of the CS lab machines, and to get your first JSP installed on the server. If you don't want to use your own computer, or if we have trouble doing the remote access, you should do the Linux setup.

You will need to access either your own computer or one of the CS lab computers for this lab. Please ask for help doing so, if you need it. You will find a copy of VNC viewer for Windows in the directory named cpsc120 on the PCCommon network drive. Other connection options are XWin32 for accessing a CS lab computer and a Windows Terminal Services client for accessing a Windows XP Professional computer.

For those working on Linux, we should make sure that each person is working on a different computer. If two people are trying to run Tomcat on the same computer, the two Tomcat servers will have to be configured to use different ports. This can be done by editing a configuration file in the conf sub-directory of the tomcat directory. The name of the file is server.xml. The port number is specified as 8080 on line 56. You can change the 8080 to any number between 1025 and about 65535. Using a port number less than 1025 would require administrative privileges. Remember that the port number must be used in the Web addresses for the server, such as http://jsmith.hws.edu:8080. Note for servers running on Windows: It should be possible to change the port number to 80. A port number of 80 can be omitted from a Web address, so that the address for your server would become something like http://jsmith.hws.edu.

Linux Setup

The software that you need to run Tomcat on the CS lab machines has already been installed, except that you must make a copy of the Tomcat server software. This can be found in the directory named jakarta-tomcat-4.0.1 in the /home/cs371 directory. Copy this directory into your home directory. You will probably want to change the name to something simpler, like tomcat. On the command line, you can say

            cp  -r  /home/cs371/jakarta-tomcat-4.0.1  tomcat

to copy and rename the directory. Its a large directory, so it will take a little while to copy it.

Windows Setup

You should have already installed the software before the start of the lab. If you need help to complete the installation, please ask for it.

For Tomcat to work on Windows, you will have to define JAVA_HOME in the file catalina.bat in the bin directory, as described in Murach, page 35.

Also, you will want to edit the file server.xml in the conf directory to make servlets reloadable, as described in Murach, page 39. (Make sure that you get the syntax exactly right, including the "/" before the final ">".)

(Note for Linux servers: The two issues discussed here are already taken care of in the Linux version.)

Starting and Stopping the Server

To start the server, you should open a command-line window and change to the bin directory in the tomcat directory. (If you are using Konqueror in Linux to view the bin directory, just hit Control-T to open a terminal window for that directory.) In fact, you could actually start and stop tomcat by clicking on program icons, but then you won't get to see the output from the program.

You can start the tomcat server by running startup.sh in Linux or startup.bat in Windows. Once it is running, you should be able to access it in any Web browser (though only from a computer on the campus network). To shut down the server, run shutdown.sh in Linux or shutdown.bat in Windows. Please do not leave your server running all the time on the CS lab computers, since it uses a hefty chunk of the computer's RAM. To test that the server is shut down, try accessing it in a Web browser. You should get a message that the connection was refused.

There is one difference between Linux and Windows: When you use startup.bat in Windows, a separate window will open where the server will print messages. In Linux, when you use startup.sh, the messages are printed to a log file. Sometimes, it will be useful to be able to see the messages. To make this easier in Linux, you can use the alternative command:

        catalina.sh  run

In this case, the server will run and print its messages in the same window where you give this command. Furthermore, you will be able to shut down the server simply by hitting Control-C in that window, and it will be stopped automatically when you close the window or when you log out. I strongly recommend using this alternative command to run the server, except in cases where you actually do want to leave the server running after you log out.

A First JSP

Once you get your server working, it will be fun to write your first JSP. As you do this, remember that the file name should end in .jsp. Also, the file name should not contain spaces or other special characters. The file should be stored (for now) in the sub-directory named ROOT inside Tomcat's webapps directory. This will make the file accessible at a Web address of the form http://jsmith.hws.edu:8080/file.jsp

A JSP is an ordinary Web page that can contain Java code in special "JSP tags". There are at least five different types of JSP tags that can be used. One of these is the JSP expression that we looked at in class. This has the form

              <%=  java-expression  %>

The java-expression can be any legal Java expression. The value of the expression is computed and will appear on the Web page that is eventually seen by a user of your server.

Another JSP tag is the JSP scriptlet, which begins with <% (with no "=") and ends with %>. In between, you can have any Java code that could appear inside a method definition. This includes, of course, things like while loops and if statements. This code will be executed when the page is requested by a user. There are several pre-defined variables that can be used in this code. One of these is out, which is a variable of type PrintWriter that can be used to write stuff onto the Web page. The variable out can be used just like System.out, except that the output will appear on the page that is presented to the user. For example, the JSP scriptlet

              <% out.print("<p>Countdown... ");
                 for (int i = 10; i >= 0; i--) {
                    out.print(i);
                    out.print(" ");
                 }
                 out.println("</p>");
              %>

Will cause "Countdown... 10 9 8 7 6 5 4 3 2 1 0" to be shown on the page.

As a first exercise, I would like you to write a JSP page that shows a table of random numbers on the web page that it produces. More particularly, it should show 100 random numbers. Each number should be an integer in the range 1 to 10000. The numbers should be arranged on ten lines, with ten numbers on each line. (If you already know how to use HTML tables, it would be nice to use a table to display the numbers. Otherwise, you can simply put <br>'s between the groups of numbers to make them come out on separate lines.) In case you have forgotten, you can get a random integer between 1 and 10000 with the Java expression

                (int)(Math.random()*10000 + 1)

To get started, you might want to write a simple page that contains no Java code, just to see that you can access the page with a web browser. Then you can start adding the Java code. While you are developing the page, you might have some Java syntax errors in your code. It will be interesting to see what happens in Tomcat when it tries to serve a JSP page that contains syntax errors.

Input Data for your Page

Now, a dynamic Web page that shows some random numbers is OK, but it's more usual for the contents of a dynamic page to depend somehow on input from the user. The user might, for example, provide the input data by filling in a form on a Web page. I'm not assuming that you already know how to use forms, so we will look at another way of providing input: in the URL that references the page. Consider the URL

      http://jsmith.hws.edu:8080/random.jsp?count=200&max=100000

The part of this URL that comes after the "?" provides data to the JSP that is being requested. This URL might mean, for example, that the user would like to see 200 random numbers chosen from the range 1 to 100000. There is only one question: In the Java code for the JSP page, how do you get the values of count and max? The answer is to use another pre-defined feature: the method request.getParameter(paramName). This returns the value of a parameter specified as input to the page. In the above example, the paramNames are count and max. For example, request.getParameter("count") would get the value, 200, specified for count. Unfortunately, it returns the value as a string. So, the commands

             String countString = request.getParameter("count");
             String maxString = request.getParameter("max");

would get the strings "200" and "100000" from the URL. To use these values effectively on your page, you will have to convert the strings to integers. As you know, code to convert countString would look something like

         int count;
         try {
             count = Integer.parseInt(countString);
         }
         catch (NumberFormatException e) {
             // Do something in the case where it's not a legal integer
         }

Assignment

To complete the exercise for this lab, you should modify your JSP page so that it can accept the parameters count and max in the URL. It should print the requested number of integers in the requested range. The numbers should still be printed ten to a line.

Don't just show the numbers on the page -- make it look better than that. You should think of this page as a "random number service," and you should include some text such as "Thanks for using my random number service." Try to make the page behave in a reasonable way when no value is provided for count or for max, or when the values that are provided are not legal integers.

You should turn in a printout of your JSP source file. Turn it in on Wednesday in class. For this first assignment, it will not be necessary to make the page available for testing on-line.

Done Before the End of Lab??

If you have extra time in lab, you can use it to explore some of the example servlets and JSP pages that come with Tomcat. You could also look at the documentation. There are links to this on the front page of your new Tomcat server.

David Eck