Here are the steps to set up the Apache Tomcat servlet container on the SEASnet machines:
1. Log in to a SEASnet machine.
2. There are four environment variables to set. Set the following environment variables:
setenv PATH /u/cs/class/cs143v/cs143vta/bin:${PATH}
setenv JAVA_HOME /u/cs/class/cs143v/cs143vta/j2sdk1.4.1_01/
setenv CATALINA_HOME /u/cs/class/cs143v/cs143vta/tomcat-4.1.17/
setenv CATALINA_BASE ${HOME}/tomcat
setenv CLASSPATH ${CATALINA_HOME}/common/lib/servlet.jar:${CLASSPATH}
Instead of setting them manually, if you are using csh, we can just "source" as follows:
source /u/cs/class/cs143v/cs143vta/bin/all.env
. This has to be done each time you login.You may want to set the above variables in your login script, so that they will be set automatically whenever you log in: add above command in your .cshrc file.
3. Run /u/cs/class/cs143v/cs143vta/bin/buildServletDir
. This only needs to be run once.It will create the following directory structure
${HOME}/tomcat
${HOME}/tomcat/logs
${HOME}/tomcat/temp
${HOME}/tomcat/work
${HOME}/tomcat/conf
${HOME}/tomcat/webapps
${HOME}/tomcat/webapps/ROOT
${HOME}/tomcat/webapps/ROOT/WEB-INF
${HOME}/tomcat/webapps/ROOT/WEB-INF/classes
${HOME}/tomcat is the home directory of your servlet server instance.
${HOME}/logs directory stores the log files generated by the server.
${HOME}/temp and ${HOME}/work directories store temporary files that the server creates.
${HOME}/webapps is the main
directory where your java program and html files would reside.
In particular,
your html files would reside in ${HOME}/tomcat/webapps/ROOT and your compiled java classes
would reside in ${HOME}/tomcat/webapps/ROOT/WEB-INF/classes
${HOME}/conf is the place for the configuration files for your server instance. There are 4 configuration files necessary to run a server: server.xml, tomcat-users.xml, web.xml, and jk2.properties. The buildDir script creates default configuration files. However, each student has to modify server.xml file to change the port number that the server uses. We explain how to do this shortly.
4. You need to modify ${HOME}/tomcat/conf/server.xml file to change the port that your server instance uses. Your server requires two ports when it runs: One for communication with a Web browser (Server Port) and the other for internal administration(Connector Port). Please check port assigment for the ports assigned to you. Let’s assume you have picked 11031 for the server port and 11032 for the connector port.From ${HOME}/tomcat/conf/server.xml file, edit the following line
<Server
port="8005" shutdown="SHUTDOWN" debug="0">
to
<Server
port="11031" shutdown="SHUTDOWN" debug="0">
Note that the port number changed from 8005 to 11031.
Also, edit the following lines
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8080" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="100" debug="0" connectionTimeout="20000"
useURIValidationHack="false" disableUploadTimeout="true" />
to
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="11032" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="100" debug="0" connectionTimeout="20000"
useURIValidationHack="false" disableUploadTimeout="true" />
Note that the port number changed from 8080 to 11032.
5. Create a test html file, say, test.html in ${HOME}/tomcat/webapps/ROOT.
Create a test java class, say, Hello.class in ${HOME}/tomcat/webapps/ROOT/WEB-INF/classes
6. Run the your Servlet server instance by running command "startup.sh"
7. Try to access your html file and java class from your browser
http://<machinename>:<port>/<filename>.html
http://<machinename>:<port>/servlet/<javaClassName>
For example, if you are running the server on landfair at port 11032 and if your java class is Hello.class, you can access it through the following URL:
http://landfair.seas.ucla.edu:11032/servlet/Hello
NOTE: This document assumes a basic knowledge of HTML. We will not be providing documentation for HTML coding apart from the creation of forms. There are dozens of tutorials available online. You might check out the NCSA Beginner's Guide to HTML.
Java Servlets are the Java solution for providing server-side services over the web by dynamically producing HTML documents, other kinds of documents, or performing other computations in response to communication from the user. They provide a very easy-to-use interface for interacting with client queries and providing server responses. Students who plan to interface with DB2 using JDBC will be working with Java Servlets.
Java Servlets interact with the user through HTML forms. For user interaction, you'll have to run a special Servlet program on a specific port on a Unix machine.
Input to Servlet programs is passed to the program using web forms. Forms include text fields, radio buttons, check boxes, popup boxes, scroll tables, and the like.
Thus retrieving input is a two-step process: you must create an HTML document that provides forms to allow users to pass information to the server, and your Servlet program must have a means for parsing the input data and determining the action to take. This mechanism is provided for you in Java Servlets.
Forms are designated within an HTML document by the fill-out form tag:
<FORM METHOD = "POST" ACTION = "http://form.url.com/servlet/serletName">
... Contents of the form ...
</FORM>
The URL given after ACTION is the URL of your program. The METHOD is the means of transferring data from the form to the program. In this example, we have used the "POST" method, which is the recommended method. There is another method called "GET", but there are common problems associated with this method. Both will be discussed in the next section.
Within the form you may have anything except another form. The tags used to create user interface objects are INPUT, SELECT, and TEXTAREA.
The INPUT tag specifies a simple input interface:
<INPUT TYPE="text" NAME="thisinput" VALUE="default" SIZE=10 MAXLENGTH=20>
<INPUT TYPE="checkbox" NAME="thisbox" VALUE="on" CHECKED>
<INPUT TYPE="radio" NAME="radio1" VALUE="1">
<INPUT TYPE="submit" VALUE="done">
<INPUT TYPE="radio" NAME="radio1" VALUE="2" CHECKED>
<INPUT TYPE="hidden" NAME="notvisible" VALUE="5">
Which would produce the following form:
The different attributes are mostly self-explanatory. The TYPE is the variety of input object that you are presenting. Valid types include "text", "password", "checkbox", "radio", "submit", "reset", and "hidden". Every input but "submit" and "reset" has a NAME which will be associated with the value returned in the input to the program. This will not be visible to the user (unless they read the HTML source). The other fields will be explained with the types:
"text" - refers to a simple text entry field. The VALUE refers to the default text within the text field, the SIZE represents the visual length of the field, and the MAXLENGTH indicates the maximum number of characters the textfield will allow. There are defaults to all of these (nothing, 20, unlimited).
"password" - the same as a normal text entry field, but characters entered are obscured.
"checkbox" - refers to a toggle button that is independently either on or off. The VALUE refers to the string sent to the server when the button is checked (unchecked boxes are disregarded). The default value is "on".
"radio" - refers to a toggle button that may be grouped with other toggle buttons such that only one in the group can be on. It's essentially the same as the checkbox, but any radio button with the same NAME attribute will be grouped with this one.
"submit" and "reset" - these are the pushbuttons on the bottom of most forms you'll see that submit the form or clear it. These are not required to have a NAME, and the VALUE refers to the label on the button. The default names are "Submit Query" and "Reset" respectively.
"hidden" - this input is invisible as far as the user interface is concerned (though don't be fooled into thinking this is some kind of security feature -- it's easy to find "hidden" fields by perusing a document source or examining the URL for a GET method). It simply creates an attribute/value binding without need for user action that gets passed transparently along when the form is submitted.
The second type of interface is the SELECT interface, which includes popup menus and scrolling tables. Here are examples of both:
<SELECT NAME="menu">
<OPTION>option 1
<OPTION>option 2
<OPTION>option 3
<OPTION SELECTED>option 4
<OPTION>option 5
<OPTION>option 6
<OPTION>option 7
</SELECT>
<SELECT NAME="scroller" MULTIPLE SIZE=7>
<OPTION SELECTED>option 1
<OPTION SELECTED>option 2
<OPTION>option 3
<OPTION>option 4
<OPTION>option 5
<OPTION>option 6
<OPTION>option 7
</SELECT>
Which will give us:
The SIZE attribute determines whether it is a menu or a scrolled list. If it is 1 or it is absent, the default is a popup menu. If it is greater than 1, then you will see a scrolled list with SIZE elements. The MULTIPLE option, which forces the select to be a scrolled list, signifies that a more than one value may be selected (by default only one value can be selected in a scrolled list).
OPTION is more or less self-explanatory -- it gives the names and values of each field in the menu or scrolled table, and you can specify which are SELECTED by default.
The final type of interface is the TEXTAREA interface:
<TEXTAREA NAME="area" ROWS=5 COLS=30>
Mary had a little lamb.
A little lamb?
A little lamb!
Mary had a little lamb.
It's fleece was white as snow.
</TEXTAREA>
As usual, the NAME is the symbolic reference to which the input will be bound when submitted to the program. The ROWS and COLS values are the visible size of the field. Any number of characters can be entered into a text area.
The default text of the text area is entered between the tags. Whitespace is supposedly respected (as between <PRE> HTML tags), including the newline after the first tag and before the last tag.
Java handles GET and POST slightly differently. The parsing of the input is done for you by Java, so you are separated from the actual format of the input data completely. Your program will be an object subclassed off of HttpServlet, the generalized Java Servlet class for handling web services.
Servlet programs must override the doGet() or doPost() messages, which are methods that are executed in response to the client. There are two arguments to these methods, HttpServletRequest request and HttpServletResponse response. Let's take a look at a very simple servlet program, the traditional HelloWorld (this time with a doGet method):
import java.io.*;
import java.text.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
public class Hello extends HttpServlet {
public void doGet(HttpServletRequest request,
HttpServletResponse response)
throws IOException, ServletException {
response.setContentType("text/html");
PrintWriter out = response.getWriter();
out.println("<html>");
out.println("<head>");
String title = "Hello World";
out.println("<title>" + title + "</title>");
out.println("</head>");
out.println("<body bgcolor=white>");
out.println("<h1>" + title + "</h1>");
String param = request.getParameter("param");
if (param != null)
out.println("Thanks for the lovely param='" + param + "' binding.");
out.println("");
out.println("");
}
}
We'll discuss points in this code again in the section on Java Output, but for now, we will focus on the input side. The argument HttpServletRequest request represents the client request, and the values of the parameters passed from the HTML FORM can be retrieved by calling the HttpServletRequest getParameter method. This method takes as its argument the name of the parameter (the name of the HTML INPUT object), and returns as a Java String the value assigned to the parameter. In cases where the parameter may have multiple bindings, the method getParameterValues can be used to retrieve the values in an array of Java Strings -- note that getParameter will return the first value of this array. It is through these mechanisms that you can retrieve any of the values entered or implicit in the form.
As might be inferred from the example above, Java returns null if the parameter for whose name you request does not have a value. Recall that unchecked buttons' bindings are not passed in a POST message -- you can check for null to determine when buttons are off.
In your project, you are going to be concerned with returning HTML documents to the user. The documents will be dynamically created based on the output of the query. You can format it however you like, using ordinary HTML formatting routines
Let's look back at our Java code example. Output is all handled by the HttpServletResponse object, which allows you to set the content type through the setContentType method. Instead of printing the HTTP header yourself, you tell the HttpServletResponse object that you want the content type to be "text/html" explicitly.
All HTML is returned to the user through a PrintWriter object, that is retrieved from the response object using the getWriter method. HTML code is then returned line by line using the println method.
Assuming that you all have a basic background in Java, so we won't provide a detailed treatment of exceptions here, but do note that IOException and ServletException both must either be handled or thrown.
You can provide your HTML FORMs on permanent webpages in your personal WWW directory -- though this isn't recommended because you then have to hard code the Servlet addresses -- or in the webpages subdirectory where you run your Servlet (see below in the Servlet setup section). Alternatively (or additionally) you can integrate FORMs into Servlets by creating a FORM on the fly in your Servlet program, which will be invoked when doPost() or doGet() are invoked by the client. An example of a program that creates a FORM on the fly can be found at RequestParamExample.java.
The special characters &, <, and >, need to be escaped as &, <, and >, respectively in HTML text (see NCSA Beginner's Guide to HTML). Moreover, special characters appearing in URL's need to be escaped, differently than when they appear in HTML text. For example, if you link on text with special characters and want to embed them into extended URLs as parameter values, you need to escape them: convert space to + or %20, convert & to %26, convert = to %3D, convert % to %25, etc. (In general, any special character can be escaped by a percent sign followed by the character's hexadecimal ASCII value.) Important: Do NOT escape the & that actually separates parameters!
Be careful not to confuse the escape strings for HTML text with those for URL's.
This document was written by
Nathan Folkert (with help from Vincent Chu) for Prof. Jennifer Widom's
CS145 class in Spring 2000; revised by Calvin Yang for Prof. Widom's CS145 class in Spring 2002. This document was most
recently revised by Jen-Ting Tony Hsiao for Prof Junghoo
Cho's CS143 class in Winter 2003.