The Example Servlets

This chapter uses the Duke's Bookstore application to illustrate the tasks involved in programming servlets. Table 14-1 lists the servlets that handle each bookstore function. Each programming task is illustrated by one or more servlets. For example, BookDetailsServlet illustrates how to handle HTTP GET requests, BookDetailsServlet and CatalogServlet show how to construct responses, and CatalogServlet illustrates how to track session information.

Table 14-1 Duke's Bookstore Example Servlets
Function	Servlet
Enter the bookstore	`BookStoreServlet`
Create the bookstore banner	`BannerServlet`
Browse the bookstore catalog	`CatalogServlet`
Put a book in a shopping cart	`CatalogServlet`, `BookDetailsServlet`
Get detailed information on a specific book	`BookDetailsServlet`
Display the shopping cart	`ShowCartServlet`
Remove one or more books from the shopping cart	`ShowCartServlet`
Buy the books in the shopping cart	`CashierServlet`
Receive an acknowledgement for the purchase	`ReceiptServlet`

The data for the bookstore application is maintained in a database and accessed through the helper class database.BookDB. The database package also contains the class BookDetails, which represents a book. The shopping cart and shopping cart items are represented by the classes cart.ShoppingCart and cart.ShoppingCartItem, respectively.

The source code for the bookstore application is located in the <JWSDP_HOME>/docs/tutorial/examples/web/bookstore1 directory created when you unzip the tutorial bundle (see Running the Examples).

In a terminal window, go to <JWSDP_HOME>/docs/tutorial/examples/web/bookstore1.

Run build. The build target will spawn any necessary compilations and copy files to the <JWSDP_HOME>/docs/tutorial/examples/web/bookstore1/build directory.

Make sure Tomcat is started.

Run ant install. The install target notifies Tomcat that the new context is available.

Start the PointBase database server and populate the database if you have not done so already (see Accessing Databases from Web Applications).

To run the application, open the bookstore URL http://localhost:8080/bookstore1/enter.

Run ant package. The package task creates a WAR file containing the application classes in WEB-INF/classes and the context.xml file in META-INF.

Make sure Tomcat is started.

Run ant deploy. The deploy target copies the WAR to Tomcat and notifies Tomcat that the new context is available.

Troubleshooting

Common Problems and Their Solutions lists some reasons why a Web client can fail. In addition, Duke's Bookstore returns the following exceptions:

BookNotFoundException--Returned if a book can't be located in the bookstore database. This will occur if you haven't loaded the bookstore database with data by running ant create-book-db or if the database server hasn't been started or it has crashed.

BooksNotFoundException--Returned if the bookstore data can't be retrieved. This will occur if you haven't loaded the bookstore database with data by running ant create-book-db or if the database server hasn't been started or it has crashed.

UnavailableException--Returned if a servlet can't retrieve the Web context attribute representing the bookstore. This will occur if you haven't copied the PointBase client library <PB_HOME>/lib/pbclient45.jar to <JWSDP_HOME>/common/lib, if the PointBase server hasn't been started, or if you have not defined a data source in Tomcat that references the PointBase database (see Defining a Data Source in Tomcat).

Because we have specified an error page, you will see the message The application is unavailable. Please try later. If you don't specify an error page, the Web container generates a default page containing the message A Servlet Exception Has Occurred and a stack trace that can help diagnose the cause of the exception. If you use the errorpage.html, you will have to look in the Web container's log to determine the cause of the exception. Web log files reside in the directory <JWSDP_HOME>/logs and are named jwsdp_log.<date>.txt.