Software Architecture Documentation (SAD)

Page tree


Contents

Architecture Background

Problem Background

Solution Background

Architecture Background


Problem Background

The Java Pet Store sample application is a working demonstration of the J2EE platform in a real application design. It was created by Sun Microsystems as part of the Java BluePrints program. This program defines the application programming model for end-to-end solutions using Java(tm) technology.

System Overview

The Java Pet Store sample application application resembles a business-to-consumer ecommerce website and the enterprise information systems (EISs) behind it. The Java Pet Store has a decoupled enterprise architecture that can interoperate with existing data sources and business partners’ systems, all built on top of the J2EE platform. This application comprises four separate sub-applications that cooperate to fulfill the enterprise'€™s business needs, each of which is a J2EE application:

  1. pet store e-commerce Web site ("petstore"€). A Web application which shoppers use to purchase merchandise through a Web browser
  2. pet store administration application ("€œpetstoreadmin"€). A Web application that enterprise administrators use to view sales statistics and manually accept or reject orders. While petstoreadmin is a Web application, its user interface is a rich client that uses XML messaging, rather than an HTML Web browser
  3. order processing center ("OPC"€). A process-oriented application that manages order fulfillment by providing the following services to other enterprise participants:
    • receives and processes XML documents, via JMS, containing orders from the petstore
    • provides petstoreadmin application with order data using XML messaging over HTTP sends email to customers acknowledging orders using JavaMail.
    • sends XML order documents to suppliers via JMS
    • maintains purchase order database
  4. supplier. A process-oriented application that manages shipping products to customers by providing the following services:
    • receives XML order documents from opc via JMS
    • ships products to customers provides manual inventory management through a Web-based interface maintains inventory database

Here is a context diagram for the applications:

Source: Designing Enterprise Applications with the J2EE Platform. Figure 11.2

The following figure "provides a high-level view of the major modules of the sample application and the application's relationship to its key participants":

Source: Designing Enterprise Applications with the J2EE Platform, Second Edition. Figure 11.4

This figure misses a reference to the type of interaction between each module, but it can give us a high level overview of what applications are related.

Context and Scope

The Java Pet Store sample application is a working application. This Wiki is an overview of how an a-priori architectural documentation would have looked like. This Wiki concentrates on the architecture of the petstore. Future additions will offer more in-depth explanation of the other sub-applications.

Driving Requirements of the Petstore

Categories and description

  • All pets should have a description, a price, and a link to add it to the shopping cart
  • All pets should be categorized according to their type and sub-type, i.e., a male chihuahua would be of type Dog, and of sub-type Chihuahua.
  • All subtypes and all pets should include a short description.

Shopping cart

  • The user should be allowed to select items to buy, group them, change the quantities, and track this information. This functionality will be described as shopping cart from now on.
  • The shopping cart should allow the user to purchase the items before placing an order. Pets can be easily added to the shopping cart. Adding pets to the cart should be as easy as possible.
  • The shopping cart should shortly describe the pets that have been added to it, their price, their quantity, and the total amount to pay.
  • There is one and only one cart per user.

User information

  • Any user should be allowed to save personal information in the website.
  • The personal information that a user may save is:
    • First name and last name
    • Street address, city, state, zip code, country
    • Telephone
    • email
    • Credit card information. number, type, expiry date
    • Store personalization options, preferred language, favorite object, banners.
    • One or more shipping addresses
  • The user should be allowed to have several shipping addresses
  • A shipping address includes the following information: label, street address, city, state, zip code, country
  • User information should only be accessible to the user and it should be protected by username and password.
  • The user should be allowed to delete or modify his/her user information.
  • Unregistered users are not allowed to purchase items

Interaction with the Order Processsing Center

  • The petstore should asynchronically communicate with the Order Processing Center (OPC).
  • Message delivery must be reliable. When the pet store sends a message, the OPC must receive and process the message exactly once.
  • If the OPC is not available when the message is sent, the message must be stored and delivered when the OPC becomes available.
  • The interface between the OPC and the pet store must be flexible. It should be easy to change the implementation of either the pet store or the OPC.
  • The interface to the OPC should be easily extendable to clients other than the pet store, including clients not written in the Java language.
  • Each order transmitted by the pet store must include a globally-unique identifier.

Purchasing

  • When the user decides to place an order (buy the items in the shopping cart), he/she must be informed that the transaction took place and be given a unique confirmation code for the transaction.

Solution Background

From the Designing Enterprise Applications with J2EE book we are told that:

"the application can be divided into modules based on functionality. Such separation reduces the dependency between modules and allows them to be developed independently. In addition, identifying interfaces between modules enables modules to be developed by third-party component providers."

In this view, the application is divided into these modules:

  • A control module to create and maintain user account information, which includes a user identifier, billing, and contact information. This information is maintained in a database. The control module also creates and manages the user's shopping cart and controls the interactions with the user.
  • A sign-on module to handle the user log-in process and security, such as verifying a user identifier and password
  • A product catalog module that returns product information from the catalog based on a user's search criteria
  • A customer module that manages a user's purchasing process and maintains account records for a customer
  • A messaging module that enables the application to send and receive asynchronous messages containing purchase orders

Architectural Approaches to the Petstore

  • Use of an MVC framework. Functional separation makes applications more reliable and easier to maintain and extend. Application components developed for a MVC framework are often more reusable, as well.
  • Separation of web and business logic. The application will use enterprise beans to have scalability, reliability, a component-based development model, and common horizontal services such as persistence, asynchronous communication,and declarative transaction and security control.
  • Local bean logic. The Pet Store site uses enterprise beans that reside on the same machine, and JVM, as their clients. This approach "improve(s) performance and simplif(ies) development". When enterprise beans are distributed among several machines the communication between components is done through remote interfaces. This "improve(s) scalability and availability, [...] but the high cost of remote communication makes them appropriate mostly for coarse-grained operations".
  • Communication. The Java Pet Store website uses both synchronous and asynchronous communication. It "accesses its catalog synchronously, because accessing a catalog is a fast operation. [It] transmits purchase orders asynchronously because orders may take a long while to complete, and the order processing center may not always be available."

Based on the Sample Application Design and Implementation article.

Analysis Results

There a no results available. Trade studies, quantitative modeling, or other analysis results have not been scheduled.

Mapping Requirements to Architecture

The following use case diagram depicts the high-level system functional requirements:

''Source: Designing Enterprise Applications with J2EE. Figure 11.3 Sample Application Use Case Diagram.

The focus of this document are the customer requirements:

  • Browse catalog. Will be addressed by several modules and views:
    • Data model view. The petstoredb view describes the elements that will be exposed.
    • Runtime view. Browse catalog works just like any other HTTP request from the user.
    • Module view. The catalog package (from the components package) directly addresses the Browse catalog use case.
  • Manage account. Similar to Browse catalog there are elements in the different views that deal with this use case:
    • Data model view. The petstoredb view describes the customer information that will be stored and can be modified.
    • Runtime view. Manage account works just like any other HTTP request from the user.
    • Module view. The following packages from the components package address the Manage account use case: signon, cart, customer, contactInfo, and address.
  • Receive customer order status. This use case is addressed by the OPC application.
  • Place orders.
    • Runtime view. Place orders works just like any other HTTP request from the user.
    • Module view. The supplierpo and purchaseorder packages from the components package address the place orders use case.
  • No labels