Duke’s Bookstore Case Study Example
We are working on a fresh, updated Jakarta EE Tutorial. This section hasn’t yet been updated. |
The Duke’s Bookstore example is a simple e-commerce application that illustrates some of the more advanced features of Jakarta Faces technology in combination with Jakarta Contexts and Dependency Injection (CDI), enterprise beans, and the Jakarta Persistence. Users can select books from an image map, view the bookstore catalog, and purchase books. No security is used in this application.
Design and Architecture of Duke’s Bookstore
Duke’s Bookstore is a simple web application that uses many features of Jakarta Faces technology, in addition to other Jakarta EE features:
-
Jakarta Faces technology, as well as Jakarta Contexts and Dependency Injection (CDI)
-
A set of Facelets pages, along with a template, provides the user interface to the application.
-
CDI managed beans are associated with each of the Facelets pages.
-
A custom image map component on the front page allows you to select a book to enter the store. Each area of the map is represented by a Jakarta Faces managed bean. Text hyperlinks are also provided for accessibility.
-
Action listeners are registered on the image map and the text links. These listeners retrieve the ID value for the selected book and store it in the session map so it can be retrieved by the managed bean for the next page.
-
The
h:dataTable
tag is used to render the book catalog and shopping cart contents dynamically. -
A custom converter is registered on the credit card field on the checkout page,
bookcashier.xhtml
, which also uses anf:validateRegEx
tag to ensure that the input is correctly formatted. -
A value-change listener is registered on the name field on
bookcashier.xhtml
. This listener saves the name in a parameter so the following page,bookreceipt.xhtml
, can access it.
-
-
Enterprise beans: Local, no-interface-view stateless session bean and singleton bean
-
A Jakarta Persistence entity
The packages of the Duke’s Bookstore application, located in the jakartaee-examples/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/
directory, are as follows:
-
components
: Includes the custom UI component classes,MapComponent
andAreaComponent
-
converters
: Includes the custom converter class,CreditCardConverter
-
ejb
: Includes two enterprise beans:-
A singleton bean,
ConfigBean
, that initializes the data in the database -
A stateless session bean,
BookRequestBean
, that contains the business logic to manage the entity
-
-
entity
: Includes theBook
entity class -
exceptions
: Includes three exception classes -
listeners
: Includes the event handler and event listener classes -
model
: Includes a model JavaBeans class -
renderers
: Includes the custom renderers for the custom UI component classes -
web.managedbeans
: Includes the managed beans for the Facelets pages -
web.messages
: Includes the resource bundle files for localized messages
The Duke’s Bookstore Interface
This section provides additional detail regarding the components of the Duke’s Bookstore example and how they interact.
The Book Persistence Entity
The Book
entity, located in the dukesbookstore.entity
package, encapsulates the book data stored by Duke’s Bookstore.
The Book
entity defines attributes used in the example:
-
A book ID
-
The author’s first name
-
The author’s surname
-
The title
-
The price
-
Whether the book is on sale
-
The publication year
-
A description of the book
-
The number of copies in the inventory
The Book
entity also defines a simple named query, findBooks
.
Enterprise Beans Used in Duke’s Bookstore
Two enterprise beans located in the dukesbookstore.ejb
package provide the business logic for Duke’s Bookstore.
-
BookRequestBean
is a stateful session bean that contains the business methods for the application. The methods create, retrieve, and purchase books, and update the inventory for a book. To retrieve the books, thegetBooks
method calls thefindBooks
named query defined in theBook
entity. -
ConfigBean
is a singleton session bean used to create the books in the catalog when the application is initially deployed. It calls thecreateBook
method defined inBookRequestBean
.
Facelets Pages and Managed Beans Used in Duke’s Bookstore
The Duke’s Bookstore application uses Facelets and its templating features to display the user interface. The Facelets pages interact with a set of CDI managed beans that act as backing beans, providing the underlying properties and methods for the user interface. The front page also interacts with the custom components used by the application.
The application uses the following Facelets pages, which are located in the jakartaee-examples/tutorial/case-studies/dukes-bookstore/src/main/webapp/
directory.
-
bookstoreTemplate.xhtml
: The template file, which specifies a header used on every page as well as the style sheet used by all the pages. The template also retrieves the language set in the web browser.Uses the
LocaleBean
managed bean. -
index.xhtml
: Landing page, which lays out the custom map and area components using managed beans configured in thefaces-config.xml
file and allows the user to select a book and advance to thebookstore.xhtml
page. -
bookstore.xhtml
: Page that allows the user to obtain details on the selected book or the featured book, to add either book to the shopping cart, and to advance to thebookcatalog.xhtml
page.Uses the
BookstoreBean
managed bean. -
bookdetails.xhtml
: Page that shows details on a book selected frombookstore.xhtml
or other pages and allows the user to add the book to the cart and/or advance to thebookcatalog.xhtml
page.Uses the
BookDetailsBean
managed bean. -
bookcatalog.xhtml
: Page that displays the books in the catalog and allows the user to add books to the shopping cart, view the details for any book, view the shopping cart, empty the shopping cart, or purchase the books in the shopping cart.Uses the
BookstoreBean
,CatalogBean
, andShoppingCart
managed beans. -
bookshowcart.xhtml
: Page that displays the contents of the shopping cart and allows the user to remove items, view the details for an item, empty the shopping cart, purchase the books in the shopping cart, or return to the catalog.Uses the
ShowCartBean
andShoppingCart
managed beans. -
bookcashier.xhtml
: Page that allows the user to purchase books, specify a shipping option, subscribe to newsletters, or join the Duke Fan Club with a purchase over a certain amount.Uses the
CashierBean
andShoppingCart
managed beans. -
bookreceipt.xhtml
: Page that confirms the user’s purchase and allows the user to return to the catalog page to continue shopping.Uses the
CashierBean
managed bean. -
bookordererror.xhtml
: Page rendered byCashierBean
if the bookstore has no more copies of a book that was ordered.
The application uses the following managed beans, which are located in the jakartaee-examples/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/web/managedbeans/
directory.
-
AbstractBean
: Contains utility methods called by other managed beans. -
BookDetailsBean
: Backing bean for thebookdetails.xhtml
page. Specifies the namedetails
. -
BookstoreBean
: Backing bean for thebookstore.xhtml
page. Specifies the namestore
. -
CashierBean
: Backing bean for thebookcashier.xhtml
andbookreceipt.xhtml
pages. -
CatalogBean
: Backing bean for thebookcatalog.xhtml
page. Specifies the namecatalog
. -
LocaleBean
: Managed bean that retrieves the current locale; used on each page. -
ShoppingCart
: Backing bean used by thebookcashier.xhtml
,bookcatalog.xhtml
, andbookshowcart.xhtml
pages. Specifies the namecart
. -
ShoppingCartItem
: Contains methods called byShoppingCart
,CatalogBean
, andShowCartBean
. -
ShowCartBean
: Backing bean for thebookshowcart.xhtml
page. Specifies the nameshowcart
.
Custom Components and Other Custom Objects Used in Duke’s Bookstore
The map and area custom components for Duke’s Bookstore, along with associated renderer, listener, and model classes, are defined in the following packages in the jakartaee-examples/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/
directory.
-
components
: Contains theMapComponent
andAreaComponent
classes. See Creating Custom Component Classes. -
listeners
: Contains theAreaSelectedEvent
class, along with other listener classes. See Handling Events for Custom Components. -
model
: Contains theImageArea
class. -
renderers
: Contains theMapRenderer
andAreaRenderer
classes. See Delegating Rendering to a Renderer.
The jakartaee-examples/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/
directory also contains a custom converter and other custom listeners not specifically tied to the custom components.
-
converters
: Contains theCreditCardConverter
class. See Creating and Using a Custom Converter. -
listeners
: Contains theLinkBookChangeListener
,MapBookChangeListener
, andNameChanged
classes. See Implementing an Event Listener.
Properties Files Used in Duke’s Bookstore
The strings used in the Duke’s Bookstore application are encapsulated into resource bundles to allow the display of localized strings in multiple locales.
The properties files, located in the jakartaee-examples/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/web/messages/
directory, consist of a default file containing English strings and three additional files for other locales.
The files are as follows:
-
Messages.properties
: Default file, containing English strings -
Messages_de.properties
: File containing German strings -
Messages_es.properties
: File containing Spanish strings -
Messages_fr.properties
: File containing French strings
The language setting in the user’s web browser determines which locale is used.
The html
tag in bookstoreTemplate.xhtml
retrieves the language setting from the language
property of LocaleBean
:
<html lang="#{localeBean.language}">
...
For more information about resource bundles, see Internationalizing and Localizing Web Applications.
The resource bundle is configured as follows in the faces-config.xml
file:
<application>
<resource-bundle>
<base-name>
ee.jakarta.tutorial.dukesbookstore.web.messages.Messages
</base-name>
<var>bundle</var>
</resource-bundle>
<locale-config>
<default-locale>en</default-locale>
<supported-locale>de</supported-locale>
<supported-locale>es</supported-locale>
<supported-locale>fr</supported-locale>
</locale-config>
</application>
This configuration means that in the Facelets pages, messages are retrieved using the prefix bundle
with the key found in the Messages_locale.properties
file, as in the following example from the index.xhtml
page:
<h:outputText style="font-weight:bold"
value="#{bundle.ChooseBook}" />
In Messages.properties
, the key string is defined as follows:
ChooseBook=Choose a Book from our Catalog
Deployment Descriptors Used in Duke’s Bookstore
The following deployment descriptors are used in Duke’s Bookstore:
-
src/main/resources/META-INF/persistence.xml
: The Jakarta Persistence configuration file -
src/main/webapp/WEB-INF/bookstore.taglib.xml
: The tag library descriptor file for the custom components -
src/main/webapp/WEB-INF/faces-config.xml
: The Jakarta Faces configuration file, which configures the managed beans for the map component as well as the resource bundles for the application -
src/main/webapp/WEB-INF/web.xml
: The web application configuration file
Running the Duke’s Bookstore Case Study Application
You can use either NetBeans IDE or Maven to build, package, deploy, and run the Duke’s Bookstore application.
To Build and Deploy Duke’s Bookstore Using NetBeans IDE
-
Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server).
-
From the File menu, choose Open Project.
-
In the Open Project dialog box, navigate to:
jakartaee-examples/tutorial/case-studies
-
Select the
dukes-bookstore
folder. -
Click Open Project.
-
In the Projects tab, right-click the
dukes-bookstore
project and select Build.This will build, package, and deploy Duke’s Bookstore to GlassFish Server.
To Build and Deploy Duke’s Bookstore Using Maven
-
Make sure that GlassFish Server has been started (see Starting and Stopping GlassFish Server), as well as the database server (see Starting and Stopping Apache Derby).
-
In a terminal window, go to:
jakartaee-examples/tutorial/case-studies/dukes-bookstore/
-
Enter the following command:
mvn install
This command builds the application and packages it in a WAR file in the
jakartaee-examples/tutorial/case-studies/dukes-bookstore/target/
directory. It then deploys the application to GlassFish Server.