J2EE Servlet/JSP Programming FAQ


Index


Getting started

To set up Sun's J2EE server, log into rack40 and run ~cps116/bin/setup-j2ee.sh. This script will install J2EE in ~/j2sdkee1.3.1/. At the end of the installation process, a few port numbers on rack40 will be assigned to you for running your J2EE server. Please take a note of the http port, as you will need it to access Web site. If you forget this number, you can look in ~j2sdkee1.3.1/config/web.properties for the value of the http.port parameter. We ask you not to change the port number as it may conflict with your classmates' J2EE servers.

The next step is to set up J2EE environment variables. If you use bash (default), run . ~cps116/j2eeprofile; if you use csh or tcsh, run source ~cps116/j2eecshrc. You might want to add these commands to your .bashrc or .cshrc, respectively, so they are executed automatically whenever you login.

To start the J2EE server, type j2ee -verbose & to run it in background. To stop the J2EE server, type j2ee -stop (this time without &).

J2EE applications are packaged in Enterprise Archive Files, with .ear suffix. While the J2EE server is running, you can deploy/install an EAR file using the command deploytool -deploy <ear_file> localhost, where <ear_file> is the name of the EAR file. To see which applications are currently running, use the command deploytool -listApps localhost. To undeploy/uninstall an application, use the command deploytool -uninstall <app_name> localhost, where <app_name> is the name of the application (one of those you see when running deploytool -listApps localhost).

Extensive J2EE documentation is available on Sun's Web site.


Running the example

We have developed an example J2EE application available for the beer drinkers' database. To set up the example application, you need to create the beer drinkers' database first by running ~cps116/examples/db-beers/setup.sh. Then, copy the application code directory to your home directory using cp -r ~cps116/examples/servlet ~/servlet. The directory structure is explained in detail in build.xml file.

To clean up the build, type ant clean in ~/servlet. To compile and package the application, type ant. Ant is a nice tool for building Java applications (analogous to make for C/C++ applications). It looks at the file build.xml (analogous to Makefile) for instructions on how to build your application. Complete ant documentation is available online.

After you have successfully packaged the application using ant, you will find the EAR file BeerDBApp.ear in ~/servlet. Make sure that J2EE is already running (you can check that by runing deploytool -listApps localhost). Then, use deploytool -deploy BeerDBApp.ear localhost to deploy the application. If everything goes smoothly, you will be able to access the application at http://rack40.cs.duke.edu:<port>/db-beers/. To uninstall the application, use deploytool -uninstall BeerDBApp localhost.


JDBC basics

You can find the JDBC documentation, together with the rest of the Java 2 Platform API's online. An example of using JDBC can be found in ~/servlet/src/db/ (after you copy the example application). Code in this directory enscapulates all interactions between the DB2 server and the rest of the application. Note the extensive use of PreparedStatement for performance. It is also possible to run java db.BeerDB in standalone mode in directory ~/servlet/build/.

This example only illustrates how to make a local connection to DB2. To connect to the DB2 server from a remote machine, change the driver class from "COM.ibm.db2.jdbc.app.DB2Driver" to "COM.ibm.db2.jdbc.net.DB2Driver", and change the connection string from "jdbc:db2:cps116" to "jdbc:db2://rack40.cs.duke.edu/cps116". Also, when calling DriverManager.getConnection(), you need to supply your user name and password (both strings) as the second and the third arguments. When running remotely, you need to copy the DB2 JDBC driver (~/servlet/lib/db2java.zip) to the remote machine and make sure the driver is in the CLASSPATH environment variable on the remote machine.


Servlet basics

The servlet concept is very simple: Instead of serving a static HTML page, the Web server executes a piece of Java code to generate the HTML output to serve to the client. You will find the servlet API with the rest of J2EE SDK API's. A tutorial on Java Web services also covers servlets.

You will find a servlet example in ~/servlet/src/ViewDrinkerServlet.java (after you copy the example application). Note that the servlet obtains the database connection object from the servlet context, which is shared by all servlets in the same application running on the same JVM. This approach allows all servlets to share a single database connection, and is much more efficient than the CGI approach where each invocation of a CGI program requires a new database connection to be made. An event listener (~/servlet/src/listener/ContextListener.java) listens to the event of the servlet context being initialized, makes a database connection, and puts it into the context.

Both the servlet and the listener need to be registered in the J2EE Web deployment descriptor file (~/servlet/etc/web.xml). In this file, you specify the mapping between a request URL and a servlet. Whenever a mapped URL is requested, the J2EE server generates the response HTML by calling the associated servlet. Ant will automatically package web.xml into the application for deployment. If you are interested in how packaging is done, read build.xml for details.

To deploy the application, you will also need to specify J2EE application deployment descriptor (~/servlet/etc/application.xml). In this file, you can specify the root URL for the deployed application. For instance, our example application can be accessed at root URL http://rack40.cs.duke.edu:<port>/db-beers/. Sun's J2EE server also requires a special runtime deployment descriptor (~/servlet/etc/sun-j2ee-ri.xml), which contains essentially the same information. Both descriptor files will be packaged automatically by ant.

When debugging your servlets, you may find it useful to peek occasionally at the error logs in ~/j2sdkee1.3.1/logs/rack40.cs.duke.edu/web/, since not all details about errors will be displayed by the Web server.


JSP basics

JSP can be regarded as a convenient way of writing servlets. In fact, the J2EE server implements JSP pages by translating them into servlets. The idea is to embed Java code in HTML using special tags, which are executed at runtime by the server to produce the final HTML response. The difference between JSP and JavaScript is that JavaScript runs on the client (by the browser), so it typically cannot access server-side resources such as databases. The JSP syntax reference is available online, and the tutorial on Java Web services also covers JSP.

JSP pages end with suffix .jsp and reside in the same directory as regular HTML pages. You will find several JSP examples in ~/servlet/web/ (after you copy the example application). When debugging a JSP page, you may find it sometimes useful to look directly at the generated servlet code. You can find the path to this .java file by examining the error messages returned by the Web server.