Java Pet Store Tutorial

The Java Pet Store is a popular J2EE example application in the J2EE Blueprints series, created by Sun Microsystems. It models an e-commerce application where customers can purchase pets online using a Web browser. The purpose of this application is to demonstrate the capabilities of the J2EE platform and is written for learning purposes (for example to illustrate the many different design patterns on various part of J2EE). It is not coded for performance and is not intended for performance benchmarks.

The Java Pet Store 1.3.2 follows the J2EE 1.3 specs which is a set of related specifications and can be seen as a single standard for implementing and deploying enterprise applications. Java Pet Store 1.3.2 demonstrates the following:
  • How to use Java Server Pages (jsp).
  • How to use Java Servlets.
  • How to use Enterprise JavaBeans (EJB).
  • How to use Java Message Service (JMS).
  • How to use JSP Standard Tag Library (JSTL).
  • How to use the Java API for XML-based RPC (JAX-RPC).
  • How to use SOAP.
  • How to exchange and process XML-based documents.
  • How to develop flexible, scalable, cross-plaform enterprise applications.
  • How to use the Java BluePrints guidelines and patterns.
  • Illustrate basic usage of J2EE technology with current best practices.
The Pet Store application comes with full source code and documentation, and the latest release can be downloaded from:

More information about Pet Store can be found at:

The is no longer available at the site. discourage people from investing time in learning it since its old, and instead encourage developers to learn the newer material.

However there are several companies using the old BluePrints Web Application Framework (WAF) where the petstore 1.3.2 demo is based on. Download the file.

Java Pet Store 1.3.2 explained

Why is it useful to study Java Pet Store?
It is recommended in your own company to develop your own software architecture reference implementation instead of using an exsisting one straight from internet (Pet Store WAF or Struts etc). By studing Pet Store (or any other framework) you can create your own reference implementation which addresses your company specific needs. You must emphasize on performance, design, flexibility, platform independency and useability. After optimizing, code reviews, refractoring and possible redesign, the final reference implementation can be used as basis for realising actual applications.

It is recommended to first study the comprehensive information provided at the
Sun Developers Network Site:

Pet Store 1.3.2:
Installing, building, using and configuring.
Pet Store 1.3.2:
Browsable code.
Pet Store 1.3.1:
Sample Application Design and Implementation.
Note: This online document can also be used for version 1.3.2.
Pet Store FAQ
J2EE Patterns Catalog:
Pattern in this catalog includes sample code from the Java Pet Store application.
Designing Enterprise Applications with the J2EE Platform, Second Edition.

The Pet Store application consists of the following functional modules:
  1. Control module
  2. Shopping Cart module
  3. SignOn module
  4. Messaging module
  5. Calalog module
  6. Customer module
Pet Store Web Application Framework (WAF):

The Java Pet Store WAF is similar to the MVC architecture.

Petstore WAF

Servlet Filter All data that goes in or out the Servlet Filter (which contains of one or more Filter components) will pass these components like a chain. The Filter components checks the client request data before passing it to the Front Controller. Filter components can easily be re-used in other applications. The Pet Store application implements 2 Filter classes:
  • Encoding Filter: Modifies country depended codes.
  • SignOn Filter: This is an authentication filter to protect resources from unauthorised access.
Filter classes can be created by implementing javax.servlet.Filter
Design Pattern used: Intercepting Filter
Front Controller The Front Controller is a servlet (com.sun.j2ee.blueprints.waf.controller.web.MainServlet).
It has 2 purposes:
  • Calls RequestProcessor processRequest(request)
  • Calls Screen Flow Manager forwardToNextScreen(request, response)
The advantage of using the Front Controller is the easy maintainability and the code is well-structured. The Front Controller does not store any session Information.
Design Pattern used: Front Controller
Request Processor
The Request Processor changes the client HTML request into an HTML Action. The Request Processor uses the Request Map
(= see <url-mapping> elements in mappings.xml), which contains the mapping between URLs and HTML Actions.
There are two mappings.xml file: For example when the user submits a form with action="" (see signon.jsp) then the Request Processor creates an CreateUserHTMLAction instance and the perform method is called.

In the Pet Store code, the CreateUserHTMLAction perform method returns the CreateUserEvent object.

Note: HTMLAction classes implements the requested services.
The perform method may return an serializable EJB Event object, which encapsulates the request and arguments, and passes it to the Web Controller. If no Event object is returned then the Screen Flow Manager is called.
Web Controller
The purpose of the Web Controler is passing the Event Object to the EJB Controller. The Web Controller makes the communication possible between Web-Tier and EJB-Tier and can be seen as a Proxy.

In the Pet Store code, the Web Controller passes the CreateUserEvent object to the EJB Controller.

In the Pet Store application the ShoppingWebController can be found. It passes the Event to the ShoppingControllerEJB.
Design Pattern used: Business Delegate
EJB Controller
The EJB Controller is a statefull session bean and receives the Event Objects from the Web Controller. The EJB Controller changes the Event Objects in EJB Action Objects by using the above mentioned mappings.xml files. Theses files contains the mapping between Events and EJBActions
(= see <event-mapping> elements in mappings.xml).

In the Pet Store code, the CreateUserEvent object maps to CreateUserEJBAction.
The EJBActions goal is to manipulate enterprise beans or other data resources to perform the desired business operations. As mentioned earlier the EJBActions are created by the EJB Controller. When the EJBAction object is created the perform method is called, which in turn calls the processEvent method and passing the EJBEvent as an argument. The processEvent method can be found in the EJBAction implementation class.

The EJBAction uses Session Facades. Session Facades are Session Beans which purpose it is to provide methods which can do complex operations applied on one or more EJBs. For example: In a Shopping Client Facade (= Session Bean) you can pass an user id and the Facade creates a Customer object and this object is used to create the Shopping Car belonging to this Customer.

If the EJBAction has done its work an Event Response Object is created which contains the status of the executed action.

In the Pet Store code, an OrderEventResponse instance is created which contains the email-address and purchase order number of the customer. The OrderEventResponse is passed to the Web-Tier.
Design Pattern used: Session Facade
Screen Flow manager
As mentioned earlier the Front Controller calls the Screen Flow Manager method forwardToNextScreen. The Screen Flow Manager decides which page to display next on screen based on the current view, results of the HTMLAction and other states. The Screen Flow Manager uses the Screen Flow Map (= see <url-mapping> elements in mappings.xml), which contains the mapping between URLs and next screen to display.

There are two ways to determine the next screen:
  • Statically: Continuing with the Pet Store code example, the next screen is screen="create_customer.screen"
  • Dynamically: A FlowHandler is used. If a FlowHandler is used the developer creates a class which implements com.sun.j2ee.blueprints.waf.controller.web.flow.FlowHandler
Template Service
The Template Service renders (=generates) the actual page when it receives the "screen" value from the Screen Flow Manager. The Template Service is a servlet (TemplateServlet) which creates a jsp file from seperate parts such as header, sidebar, footer. To determine which parts are used to create the final page, the file screendefinitions_<language>_<country>.xml (for example: screendefinitions_en_US.xml) is being used. The data which are displayed on the jsp file are not retrieved from the response but by using EJBs which retrieves data from the database. The Custom Tag "InsertTag" inserts the jsp parts in the final template.jsp.
Enterprise Beans
There are several EJBs used in the Pet Store application.
  • Entity Bean with CMP to retrieve data from the database.
    Note: DAO can be used to retrieve data from the database. A Fast Lane Reader (e.g. CatalogHelper) has been created to switch between EJB (CatalogEJB) and DAO (e.g. CalalogDAO).
  • Session Beans (e.g. CatalogEJB, ShoppingControllerEJB)