The Example Servlets

This chapter uses the Duke's Bookstore application to illustrate the tasks involved in programming servlets. Table 11-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 11-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
Send an acknowledgment of the purchase	ReceiptServlet

The data for the bookstore application is maintained in a database and accessed through the database access class database.BookDBAO. 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 <INSTALL>/j2eetutorial14/examples/web/bookstore1/ directory, which is created when you unzip the tutorial bundle (see Building the Examples). A sample bookstore1.war is provided in <INSTALL>/j2eetutorial14/examples/web/provided-wars/. To build the application, follow these steps:

Build and package the bookstore common files as described in Duke's Bookstore Examples.
In a terminal window, go to <INSTALL>/j2eetutorial14/examples/web/bookstore1/.
Run asant build. This target will spawn any necessary compilations and copy files to the <INSTALL>/j2eetutorial14/examples/web/bookstore1/build/ directory.
Start the Application Server.
Perform all the operations described in Accessing Databases from Web Applications.

To package and deploy the example using asant, follow these steps:

In a terminal window, go to <INSTALL>/j2eetutorial14/examples/web/bookstore1/.
Run asant create-bookstore-war.
Run asant deploy-war.

To learn how to configure the example, use deploytool to package and deploy it:

Start deploytool.
Create a web application called bookstore1 by running the New Web Component wizard. Select FileRight ArrowNewRight ArrowWeb Component.
In the New Web Component wizard:
Select the Create New Stand-Alone WAR Module radio button.
In the WAR File field, enter <INSTALL>/j2eetutorial14/examples/web/bookstore1/bookstore1.war. The WAR Display Name field will show bookstore1.
In the Context Root field, enter /bookstore1.
Click Edit Contents.
In the Edit Archive Contents dialog box, navigate to <INSTALL>/j2eetutorial14/examples/web/bookstore1/build/. Select errorpage.html, duke.books.gif, and the servlets, database, filters, listeners, and util packages. Click Add.
Add the shared bookstore library. Navigate to <INSTALL>/j2eetutorial14/examples/web/bookstore/dist/. Select bookstore.jar and click Add.
Click OK.
Click Next.
Select the Servlet radio button.
Click Next.
Select BannerServlet from the Servlet Class combo box.
Click Finish.
Add the rest of the web components listed in Table 11-2. For each servlet:
Select FileRight ArrowNewRight ArrowWeb Component.
Click the Add to Existing WAR Module radio button. Because the WAR contains all the servlet classes, you do not have to add any more content.
Click Next.
Select the Servlet radio button.
Click Next.
Select the servlet from the Servlet Class combo box.
Click Finish.

Table 11-2 Duke's Bookstore Web Components

Web Component Name	Servlet Class	Alias
BannerServlet	BannerServlet	/banner
BookStoreServlet	BookStoreServlet	/bookstore
CatalogServlet	CatalogServlet	/bookcatalog
BookDetailsServlet	BookDetailsServlet	/bookdetails
ShowCartServlet	ShowCartServlet	/bookshowcart
CashierServlet	CashierServlet	/bookcashier
ReceiptServlet	ReceiptServlet	/bookreceipt

Set the alias for each web component.
Select the component.
Select the Aliases tab.
Click the Add button.
Enter the alias.
Add the listener class listeners.ContextListener (described in Handling Servlet Life-Cycle Events).
Select the Event Listeners tab.
Click Add.
Select the listeners.ContextListener class from the drop-down field in the Event Listener Classes pane.
Add an error page (described in Handling Errors).
Select the File Ref's tab.
In the Error Mapping pane, click Add Error.
Enter exception.BookNotFoundException in the Error/Exception field.
Enter /errorpage.html in the Resource to be Called field.
Repeat for exception.BooksNotFoundException and javax.servlet.UnavailableException.
Add the filters filters.HitCounterFilter and filters.OrderFilter (described in Filtering Requests and Responses).
Select the Filter Mapping tab.
Click Edit Filter List.
Click Add Filter.
Select filters.HitCounterFilter from the Filter Class column. deploytool will automatically enter HitCounterFilter in the Filter Name column.
Click Add Filter.
Select filters.OrderFilter from the Filter Class column. deploytool will automatically enter OrderFilter in the Filter Name column.
Click OK.
Click Add.
Select HitCounterFilter from the Filter Name drop-down menu.
Select the Filter this Servlet radio button in the Filter Target frame.
Select BookStoreServlet from the Servlet Name drop-down menu.
Click OK.
Repeat for OrderFilter. Select ReceiptServlet from the Servlet Name drop-down menu.
Add a resource reference for the database.
Select the Resource Ref's tab.
Click Add.
Enter jdbc/BookDB in the Coded Name field.
Accept the default type javax.sql.DataSource.
Accept the default authorization Container.
Accept the default selected Shareable.
Enter jdbc/BookDB in the JNDI name field of the Sun-specific Settings frame.
Select FileRight ArrowSave.
Deploy the application.
Select ToolsRight ArrowDeploy.
In the Connection Settings frame, enter the user name and password you specified when you installed the Application Server.
Click OK.

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

Troubleshooting

The Duke's Bookstore database access object 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 asant create-db_common 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 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 the database server hasn't been started.

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 you diagnose the cause of the exception. If you use errorpage.html, you will have to look in the server log to determine the cause of the exception.