Design and Architecture of Duke's Forest (original) (raw)

Duke’s Forest is a complex application consisting of three main projects and three subprojects. Figure 62-1 shows the architecture of the three main projects that you will deploy: Duke’s Store, Duke’s Shipment, and Duke’s Payment. It also shows how Duke’s Store makes use of the Events and Entities projects.

Figure 62-1 Architecture of the Duke’s Forest Example Application

This figure shows the architecture of the main Duke’s Forest projects and how they use the Events and Entities projects.

Duke’s Forest uses the following Java EE platform features:

The Duke’s Forest application has two main user interfaces, both packaged within the Duke’s Store WAR file:

The Duke’s Shipment application also has a user interface, accessible to administrators.

Figure 62-2 shows how the web applications and the web service interact.

Figure 62-2 Interactions between Duke’s Forest Components

This figure shows the interactions between the Duke’s Store and Duke’s Shipment projects (using REST and HTTP), and between the Duke’s Store and Duke’s Payment projects (using REST and HTTP).

As illustrated in Figure 62-2, the customer interacts with the main interface of Duke’s Store, while the administrator interacts with the administration interface. Both interfaces access a façade consisting of managed beans and stateless session beans, which in turn interact with the entities that represent database tables. The façade also interacts with web services APIs that access the Duke’s Payment web service. When the payment for an order is approved, Duke’s Store sends the order to a JMS queue. The administrator also interacts with the interface of Duke’s Shipment, which can be accessed either directly through Duke’s Shipment or from the administration interface of Duke’s Store by means of a web service. When the administrator approves an order for shipping, Duke’s Shipment consumes the order from the JMS queue.

The most fundamental building blocks of the application are the Events and Entities projects, which are bundled into Duke’s Store and Duke’s Shipment along with the Duke’s Resources project.

The events Project

Events are one of the core components of Duke’s Forest. The eventsproject, included in all three of the main projects, is the most simple project of the application. It has only one class, OrderEvent, but this class is responsible for most of the messages between objects in the application.

The application can send messages based on events to different components and react to them based on the qualification of the event. The application supports the following qualifiers:

The following code snippet from the PaymentHandler class of Duke’s Store shows how the @Paid event is handled:

@Inject @Paid Event<OrderEvent> eventManager;

...
public void onNewOrder(@Observes @New OrderEvent event) {

    if (processPayment(event)) {
        orderBean.setOrderStatus(event.getOrderID(),
                String.valueOf(OrderBean.Status.PENDING_PAYMENT.getStatus()));
        logger.info("Payment Approved");
        eventManager.fire(event);
    } else {
        orderBean.setOrderStatus(event.getOrderID(),
                String.valueOf(OrderBean.Status.CANCELLED_PAYMENT.getStatus()));
        logger.info("Payment Denied");
    }
}

To enable users to add more events to the project easily or update an event class with more fields for a new client, this component is a separate project within the application.

The entities Project

The entities project is a Java Persistence API (JPA) project used by both Duke’s Store and Duke’s Shipment. It is generated from the database schema shown in Figure 62-3 and is also used as a base for the entities consumed and produced by the web services through JAXB. Each entity has validation rules based on business requirements, specified using Bean Validation.

Figure 62-3 Duke’s Forest Database Tables and Their Relationships

This figure shows the database tables in Duke’s Forest and their relationships.

The database schema contains eight tables:

The entity classes that correspond to these tables are as follows.

The dukes-payment Project

The dukes-payment project is a web project that holds a simple Payment web service. Since this is an example application, it does not obtain any real credit information or even customer status to validate the payment. For now, the only rule imposed by the payment system is to deny all orders above $1,000. This application illustrates a common scenario where a third-party payment service is used to validate credit cards or bank payments.

The project uses HTTP Basic Authentication and JAAS (Java Authentication and Authorization Service) to authenticate a customer to a JAX-RS web service. The implementation itself exposes a simple method,processPayment, which receives an OrderEvent to evaluate and approve or deny the order payment. The method is called from the checkout process of Duke’s Store.

The dukes-resources Project

The dukes-resources project contains a number of files used by both Duke’s Store and Duke’s Shipment, bundled into a JAR file placed in the classpath. The resources are in the src/main/resources directory:

The Duke’s Store Project

Duke’s Store, a web application, is the core application of Duke’s Forest. It is responsible for the main store interface for customers as well as the administration interface.

The main interface of Duke’s Store allows the user to perform the following tasks:

The administration interface of Duke’s Store allows administrators to perform the following tasks:

The project also uses stateless session beans as façades for interactions with the JPA entities described in The entities Project, and CDI managed beans as controllers for interactions with Facelets pages. The project thus follows the MVC (Model-View-Controller) pattern and applies the same pattern to all entities and pages, as in the following example.

ProductBean begins as follows:

@Stateless
public class ProductBean extends AbstractFacade<Product> {
    private static final Logger logger =
        Logger.getLogger(ProductBean.class.getCanonicalName());

    @PersistenceContext(unitName="forestPU")
    private EntityManager em;

    @Override
    protected EntityManager getEntityManager() {
        return em;
    }
    ...

Enterprise Beans Used in Duke’s Store

The enterprise beans used in Duke’s Store provide the business logic for the application and are located in the com.forest.ejb package. All are stateless session beans.

AbstractFacade is not an enterprise bean but an abstract class that implements common operations for Type<T>, where <T> is a JPA entity.

Most of the other beans extend AbstractFacade, inject thePersistenceContext, and implement any needed custom methods:

The ShoppingCart class, although it is in the ejb package, is a CDI managed bean with conversation scope, which means that the request information will persist across multiple requests. Also, ShoppingCartis responsible for starting the event chain for customer orders, which invokes the RESTful web service in dukes-payment and publishes an order to the JMS queue for shipping approval if the payment is successful.

Facelets Files Used in the Main Interface of Duke’s Store

Like the other case study examples, Duke’s Store uses Facelets to display the user interface. The main interface uses a large number of Facelets pages to display different areas. The pages are grouped into directories based on which module they handle.

Facelets Files Used in the Administration Interface of Duke’s Store

The Facelets pages for the administration interface of Duke’s Store are found in the web/admin directory:

Managed Beans Used in Duke’s Store

Duke’s Store uses the following CDI managed beans, which correspond to the enterprise beans. The beans are in the com.forest.web package:

Helper Classes Used in Duke’s Store

The CDI managed beans in the main interface of Duke’s Store use the following helper classes, found in the com.forest.web.util package:

Qualifiers Used in Duke’s Store

Duke’s Store defines the following qualifiers in thecom.forest.qualifiers package:

Event Handlers Used in Duke’s Store

Duke’s Store defines event handlers related to the OrderEvent class packaged in the events project (see The events Project). The event handlers are in the com.forest.handlers package.

Deployment Descriptors Used in Duke’s Store

Duke’s Store uses the following deployment descriptors, located in theweb/WEB-INF directory:

The Duke’s Shipment Project

Duke’s Shipment is a web application with a login page, a main Facelets page, and some other objects. This application, which is accessible only to administrators, consumes orders from a JMS queue and calls the RESTful web service exposed by Duke’s Store to update the order status. The main page of Duke’s Shipment shows a list of orders pending shipping approval and a list of shipped orders. The administrator can approve or deny orders for shipping. If approved, the order is shipped, and it appears under the Shipped heading. If denied, the order disappears from the page, and on the customer’s Orders list it appears as cancelled.

There is also a gear icon on the Pending list that makes an Ajax call to the Order Service to refresh the list without refreshing the page. The code looks like this:

<h:commandLink>
    <h:graphicImage library="img" title="Check for new orders"
                    style="border:0px" name="refresh.png"/>
    <f:ajax execute="@form" render="@form" />
</h:commandLink>

Enterprise Beans Used in Duke’s Shipment

The UserBean stateless session bean used in Duke’s Shipment provides the business logic for the application and is located in thecom.forest.shipment.session package.

Like Duke’s Store, Duke’s Shipment uses the AbstractFacade class. This class is not an enterprise bean but an abstract class that implements common operations for Type<T>, where <T> is a JPA entity.

The OrderBrowser stateless session bean, located in thecom.forest.shipment.ejb package, has one method that browses the JMS order queue and another that consumes an order message after the administrator approves or denies the order for shipment.

Facelets Files Used in Duke’s Shipment

Duke’s Shipment has only one page, so it has many fewer Facelets files than Duke’s Store.

Managed Beans Used in Duke’s Shipment

Duke’s Shipment uses the following CDI managed beans, in thecom.forest.shipment package:

Helper Class Used in Duke’s Shipment

The Duke’s Shipment managed beans use only one helper class, found in the com.forest.shipment.web.util package:

Qualifier Used in Duke’s Shipment

Duke’s Shipment includes the @LoggedIn qualifier described inQualifiers Used in Duke’s Store.

Deployment Descriptors Used in Duke’s Shipment

Duke’s Shipment uses the following deployment descriptors: