Samples

Chapter 4 SilverBooksPortal Application

This chapter describes the SilverBooksPortal sample application. It contains the following sections:

About the SilverBooksPortal application

SilverBooksPortal is the Director version of SilverBooks, a sample application provided with the SilverStream eXtend Application Server. SilverBooks Corporation is a fictitious Web-based retail bookstore. Users can browse the site, search for books, create an account, and use a shopping cart to place orders.

The purpose of the SilverBooks application is to demonstrate:

An implementation of an e-commerce Web site using the Director Content Management subsystem
How Director can be used with J2EE standards and the Struts Framework architecture

Using SilverStream eXtend Workbench and eXtend Director, you can easily modify SilverBooksPortal source files and application content, and quickly rebuild and redeploy the application.

Technologies used in SilverBooksPortal

SilverBooksPortal incorporates J2EE standard technologies to implement the Struts Framework and Model-View-Controller (MVC) design paradigm. The following technologies are described:

Struts and MVC architecture

SilverBooksPortal implements the Struts Framework and the Model-View-Controller (MVC) design paradigm by including these components:

Component	Description
Model	A set of form classes that hold the data that is updated by JSP pages.
View	JSP pages that render the front-end interface. These JSP pages insert dynamic content based on the interpretation of action tags at page request time.
Controller	An action servlet that dispatches requests to action classes to perform business logic, such as searching for a book or displaying book details when a user clicks a book title. The action servlet also provides the View component with the user interface to be displayed after the action is completed.

The major benefit of this approach is that it logically separates the key functions of the application—actions, data access, and presentation—to allow role-specific assignments, ease of maintenance, and efficient debugging.

For more information about Struts Framework and the MVC design paradigm, see the Struts Framework Project Web site.

JSP pages

JSP pages are used to implement the View component of the MVC design paradigm. SilverBooksPortal uses JSP pages to present both the static and the dynamic content of the bookstore application.

Static The following JSP pages display data that changes infrequently if at all in SilverBooksPortal:

Top navigation bar
Bottom navigation bar
Book category list
Featured book list

Because the navigation bars never change, these JSP pages are reused throughout the application.

Dynamic A more dynamic use of JSP pages in SilverBooksPortal is for presenting details about a book that has been selected from search results by the end user. When a user clicks a book title hyperlink, control passes to a JSP page called bookdetail.jsp. This JSP page in turn calls properties on a JavaBean called BookBean.java to determine how to present data about the book the user selected.

For more information about JSP pages, see:

SilverStream eXtend Director Core Development Guide
SilverStream eXtend Workbench Development Guide

Action servlets

The action servlet is the cornerstone of the Controller component of the MVC design paradigm. In SilverBooksPortal, the action servlet performs three key functions:

Receives requests from the client—in this case, a user interacting with the SilverBooksPortal application in a Web browser
Determines the action to perform
Delegates to an appropriate View component the responsibility for producing the next part of the user interface

Two XML specifications are used to configure the action servlet. The specification in web.xml associates the URL pattern *.do with the action servlet. This association means that any URL request or post ending in .do will go to the action servlet for processing. The specification in struts-config.xml maps each possible client request to an action class that performs the appropriate business logic or handles the possible exceptions.

For example, here is one of the URL mappings in struts-config.xml:

  <action path="/bookDetail" actionClass="com.sssw.demo.silverbooks.action.DetailAction">
  <forward name="success" path="/bookdetail.jsp" />
  </action>

This mapping means that when the URL bookDetail.do is requested, the action servlet instantiates the DetailAction class (or uses one that has already been instantiated) to display the detail data about a book selected by the user. The book identifier is passed as a parameter on the URL. This action class has access to a forward-mapping address called success that is mapped to the relative URL bookdetail.jsp.

The DetailAction class services the client request as follows:

Gets a reference to the book in the EJB data source, based on the book identifier (each book is represented by a book bean)
Retrieves the book data and places the book in the session
If no exceptions occur, passes control to the JSP page bookdetail.jsp, which calls properties on the book bean to determine how to display the page

The shopping cart works in a similar way. When a user decides to add a book to the shopping cart, the URL cart.do is requested, causing the action servlet to pass control to the AddCartAction class along with two parameters on the URL: add as the action, and the book identifier.

Form classes

Form classes represent the Model component of the MVC design paradigm. For example, the checkout and account detail pages use the form classes PaymentForm.java and AccountDetailForm.java to store data about customers' orders. When the data is updated, the application calls the validate() method on these form classes to ensure the accuracy of the information.

Enterprise JavaBeans

Enterprise JavaBeans (EJBs) represent business logic and manage data access in the MVC paradigm. EJBs are referenced by action servlets and form classes.

In SilverBooksPortal, EJB session beans perform two key functions:

Function	Details
Data access	Retrieve data from the Director Content Management subsystem, including: Customer order and order detail data Book data, including title, author, publisher, category, and images Most of the code that uses the Content Management API can be seen in the following source file (under the samples\SilverBooks directory in the Director installation directory): accessdata\src\com\sssw\demo\silverbooks\ejb\sessionbeans\ AccessDataBean.java
Shopping cart management	Keep track of shopping cart values from page to page.

Function

Details

Data access

Retrieve data from the Director Content Management subsystem, including:

Customer order and order detail data
Book data, including title, author, publisher, category, and images

Most of the code that uses the Content Management API can be seen in the following source file (under the samples\SilverBooks directory in the Director installation directory):

  accessdata\src\com\sssw\demo\silverbooks\ejb\sessionbeans\
AccessDataBean.java

Shopping cart management

Keep track of shopping cart values from page to page.

For more information about EJBs, see the chapter on developing EJBs in the SilverStream eXtend Workbench Development Guide.

Internationalization

The Struts Framework provides a methodology for internationalizing prompts and messages in a Web application. SilverBooksPortal implements this feature with Java resource bundles that use name/value pairs to translate static text labels to the language selected by the user. Each language supported by SilverBooksPortal has its own resource bundle.

For more information about internationalization in the Struts Framework, see:

  http://jakarta.apache.org/struts/userGuide/building_view.html#i18n

Setting up the SilverBooksPortal application

Requirements

Before you can install and run the SilverBooksPortal application:

Your computer must be running Windows NT or Windows 2000.
SilverStream eXtend Application Server must be running.
NOTE The SilverBooksPortal application provided with Director 4.0.1 has been upgraded to J2EE version 1.3. To use the application you must use SilverStream Server 4.0 or later.
SilverStream eXtend Workbench and Director must be installed.
NOTE The examples in this section assume that the SilverBooksPortal application is built and deployed on the same computer (referred to as localhost).
A database must be available to the application server that will host your application. The examples in this chapter assume the name of the database is Director.
NOTE If you are using Oracle or Sybase as your database, change the database name in your /SilverBooks/AddDBOracle.bat or AddDBSybase.bat file from DirSampleDB to Director.

For information about deploying a database, see the Core Development Guide.

Procedures

The SilverBooksPortal sample application files are copied to disk as part of the Director installation procedure. They are located in the following directory:

  %SILVERSTREAM_DIRECTOR_HOME%\samples\SilverBooks

The environment variable %SILVERSTREAM_DIRECTOR_HOME% is defined by the installation procedure.

Procedure To create the new project:

Create a custom Director EAR as described in the Core Development Guide.
Name the project SilverBooksPortal.
If you are running Director 4.0.1, specify J2EE version 1.3 (the default is 1.2).
Use the standard Director template. The Director template directory is:
```
  %SILVERSTREAM_DIRECTOR_HOME%\templates\Director
```
Select the following subsystems:
- Directory
- Framework
- Search
- Security
- User
- Content Management
- Portal
- PMC
In the Framework Configuration panel, set the database to Director and change the Locksmith user from admin to anonymous.

Procedure To add the SilverBooks sample application:

Select Project>Director EAR>Setup.
Set the template directory to:
```
  %SILVERSTREAM_DIRECTOR_HOME%\samples
```
Select SilverBooks.

Procedure To create a deployment plan:

Create a deployment plan as described in the Core Development Guide.
Assign the following JNDI names to the session beans:
```
  <beanJNDIName>sssw/SilverBooksPortal/AccessData</beanJNDIName>
  <beanJNDIName>sssw/SilverBooksPortal/ShoppingCart</beanJNDIName>
```
NOTE If you are using the SilverBooksPortal application provided with Director 4.0.1, you must assign the JNDI name to the remote interface as well as the local interface.

Map the datasource to your database name (Director). Change:

  <resourceReference isObject="true">
  	 	 <name type="String">jdbc/SilverBooksDataSource</name>
  </resourceReference>

to:

  <resourceReference isObject="true">
  	 	 <name type="String">jdbc/SilverBooksDataSource</name>
  	 	 <dataSource>Director</dataSource>
  </resourceReference>

Procedure To deploy the project:

Set the Project>Deployment Settings to localhost.
Rebuild all, archive, and deploy.

Procedure To import the Content Management data:

Open a Web browser to the PMC Import Utility:

  http://localhost/Director/SilverBooksPortal/PMC/main/pages/PmcImportPage.html

For the Data Import Archive, browse to:

  SilverBooksPortal/SilverBooks/ImportData/contentmgmt_data.zip

Click Import. A summary dialog box will appear after the import is done. (The process takes about 10 minutes.)

Running the SilverBooksPortal application

Once you have completed the processes described under Setting up the SilverBooksPortal application, you can run the application in a Web browser.

Procedure To run the SilverBooksPortal application:

Enter this URL:

  http://localhost/Director/SilverBooksPortal/silverbooks/

The home page opens in your browser:

spSBAppSilverBooksWindow

You can interact with the SilverBooksPortal application by:

Searching book titles, authors, and subjects
Creating an account
Adding items to your shopping cart
Placing orders
Selecting a different language for displaying static text

Accessing SilverBooksPortal using the PMC

The content used by the SilverBooksPortal application (including authors, books, categories, folders, customers, and orders) is maintained in the Director Content Management subsystem. This provides functionality for viewing, changing, versioning, and publishing the various content used by the application.

To provide an example, this section shows how to access SilverBooksPortal application content using the Portal Management Console (PMC). However, since SilverBooksPortal stores its content in the Director Content Management subsystem, you can perform all the usual content management operations using all the available interfaces to the Content Management subsystem, including:

Portal Management Console (PMC)
Content Management Application Programming Interface (API)
Content Management tag library
WebDAV subsystem access to the Content Management subsystem

For more information about these interfaces to the Content Management subsystem, see the Content Management Guide.

Viewing the content using the PMC

You can use the Portal Management Console (PMC) to view, modify, version, and publish the content of the SilverBooksPortal application.

Procedure To view content SilverBooksPortal application using the PMC:

Enter this URL:

  http://localhost/Director/SilverBooksPortal/PMC/main/pages/PmcFolders.html

In the login window that appears, log in using a valid account.
NOTE If you specified a Locksmith account other than anonymous when creating your Director EAR, you must use an account that has content administrative rights to log in. Otherwise, you cannot view or modify objects that appear on the Templates tab in the PMC.

Once you have logged in, the content is visible on the Content tab of the PMC. (In this example, the folder structure has been expanded to view the list of authors.)

Samples