Skip navigation.
Downloads | Product Documentation | Support

Installation Guide

# Sample Retail Application Overview

This is a brief overview of the Avitek Sample Retail Application (RTLApp) that is included with a complete BEA AquaLogic Data Services Platform (DSP) installation. This chapter describes the data sources and other application components used to develop the RTLApp.

- Quick Start Instructions for the Avitek Sample Application (RTLApp)
- Challenge of Disparate Data
- Business Case for the Avitek Self-Service Web Site
- Purpose of the Avitek RTLApp
- Running Retail Sample Application in a Browser
- Viewing RTLApp Source
- Where To Go From Here

## About Avitek Ltd.

Avitek is an imaginary retailer that has grown through acquisitions. The company started out selling apparel but recently merged with an electronic retailer to expand business and consolidate cost centers such as accounting and web development. Because of this acquisition the company now has two very different order management systems (OMS), one each for electronics and apparel orders. Avitek also has a customer relationship management (CRM) system to manage customer profile information. Finally, Avitek has a Customer Service system to manage the support cases for Electronic products.

### General IT Goals

General immediate and mid-range goals for the newly consolidated IT department include:

- An easy solution to providing integration of different back-end resources.
- An easy solution to providing read/update to these back-end resources.
- An abstraction layer to hide the complexities of interacting with different systems.

### Specific Projects

An early "low-hanging fruit" project is to build a customer self-service web site which can also be used by support representatives. This web site needs to provide an easy solution to integrating different back-end resources and to providing two-way communication (read/update). It will also need to provide an abstraction layer to hide the complexities in the different systems.

The front-end architecture of the web site will provide a Java-based Customer Self-Service portal where customers can update their profile information and review or modify their orders. The back-end architecture will access the following five different sources of data (as shown in Figure 5-1):

- Customer related information stored in a CRM database (Oracle)
- Credit card information from a billing system (Sybase)
- Case information from a support database (DB2)
- Apparel order information from the company's Order Management system (SQL Server)
- Electronics Order System accessed through a web service. (The original source of information is mainframe inherited with the merger.)

The project also needs a code name. RTLApp is selected.

Figure 5-1 RTLApp Front and Back End Architecture

# Quick Start Instructions for the Avitek Sample Application (RTLApp)

Both the RTLApp development environment and web application are available. To start the RTLApp in the IDE, follow the instructions outline in Verifying the Installation, including starting your BEA WebLogic Server.

The steps involved in running RTLApp from inside WebLogic Workshop are similar to starting the IDE:

1. Start the DSP sample domain using the Windows Start menu:

>     Start —> All Programs —> BEA WebLogic Platform 8.1 —> BEA AquaLogic Data Services Platform 2.0 —> Examples —> RTL Demo —> Launch RTL Demo Sample Server

Note: You can go on to Step 2 while starting the sample domain server.

2. Open WebLogic Workshop and the RTLApp by executing the `RTLApp.work` file located in the following directory:

>     <WL_HOME>/samples/liquiddata/RTLApp/RTLApp.work

3. Build RTLApp.

Right-click on RTLApp (top node in the Application pane), and choose Build Application from the context-sensitive menu. WebLogic Workshop displays the status of the build. Confirm that the build was successful, as indicated by the build status messages.

4. Double-click on the Java page flow file `demoPageFlowController.jpf`. It is located in the following folder:

>     RTLSelfService\Pages

5. With the page flow diagram in your work area choose the Start option from the Workshop Debug menu.

>     Debug —> Start

Log in using one of the names shown in the dialog box. Simply move your mouse over the login name of your choice to automatically fill-in the name and password (Figure 5-2).

Figure 5-2 RTLApp Login Page

# Challenge of Disparate Data

The sample retail application illustrates in simplified form the kinds of data integration challenges often encountered by Information Technology (IT) managers and staff. Issues include:

- What is the best way to normalize data drawn from widely divergent sources?
- Having normalized the data, can you access it, ideally through a single point of access.
- Having such a single point of access to your data, can you develop reusable queries that are easily tested, stored, and retrieved?
- Once you can query data, can you as easily update it in a secure manner?
- Can you cache data to improve performance while protecting users from stale information?
- How difficult is it to consume query results in client applications?

Other questions may occur. Is the data-rich solution scalable? Is it reusable throughout the enterprise? Are the original data sources transparent to the application — or do they become an issue each time you want to make a minor adjustment? When changes to underlying data inevitably occur, how difficult will it be to propagate those changes to the application layer?

So many questions...

# Business Case for the Avitek Self-Service Web Site

A survey commissioned by Avitek Marketing found customers to be dissatisfied with the call-in wait time required to track orders or update customer information. In a focus group the idea of a self-service web site resonated. Customer Service agreed; they have been requesting such a site for years, but the internal costs were always above budget. But now that Marketing is on board ...

## Web Site Design Requirements

Site requirements seem simple. Fulfillment identifies that customers will need to be able to:

- Securely log in and out.
- Review order status. A Home page will provide information on open orders, including product names and quantities of items ordered, order amount, shipping instructions, and a summary of any open customer service cases, with details.
- Review order history.
- Review and change personal profile information.
- Search through orders. A sample page provides the ability to retrieve orders based on a range of prices, range of dates, etc.

Bottom line: If customers can perform this level of self-service the company will save a lot of money.

### Maintenance Requirements

A cross-sectional team of marketing and customer service develop maintenance requirements for the web application:

- 7x24
- Less than 10 pages
- Low-maintenance
- Easily modified

### Design Requirements

An application/UI designer begins "specing out" the required JSPs. Pages are the easy part. Data is needed so he shoots off an email to the consolidated IT department.

### Information Technology (IT) Weighs In: The Moment of Truth

When an IT data architect analyzes the requirements she turns up a problem. In surveying the information needed by the application -- customer data for one data source, order data from two very separate divisions of the company (two more data sources), and customer support data (a fourth data source) — the architect realizes that integrating data from these diverse data sources will be complicated and time consuming with additional maintenance problems down the road. Challenges included:

- Cost of development. Writing the code to access and integrate data from multiple diverse data sources would take more time than originally expected and require more expensive and scarcer resources.
- Time to market. Developing and testing an application against multiple data sources would extend beyond the date when the application is needed.
- Cost of testing and maintenance. High.

Perhaps most frustrating: little of the specialized code needed by the application can be reused.

So much for low-hanging fruit.

## Search for an Alternative

Developing a unified view into distributed data is one of the most persistent challenges faced by IT departments. Just when you get all the available data sources normalized, new sources appear that must be dealt with, but which also make yesterday's data integration solution obsolete.

This problem is so pervasive that each year thousands of arguably critically-needed applications go unwritten, are delayed, or are delivered in highly-compromised form because of the data integration challenges faced by even the most sophisticated enterprises.

Compared to the above, the RTLApp team preferred a solution that:

- Provides a layer of data abstraction so that queries can treat highly-divergent data sources as a single, virtual data source.
- Allows development of human-readable, reusable queries.
- Can be easily accessed by consuming applications through a simple API.
- Protects the integrity and security of the underlying data.
- Allows read-write testing and deployment.

## A Possible Solution

When Avitek looked at Data Services Platform, they found a product that addressed the underlying challenges posed by the apparently simple RTLApp:

- Addressing the problem of data access, DSP provides data integration through a highly-accessible graphical interface.
- In DSP, queries are developed graphically and are self-describing.
- Once data integration is achieved, persistent queries are generated.
- Read-write to live or staged data is available at every step of the development process.

Specifically, the features that the team found most appealing included:

Data Access. DSP allows the application to access information from anywhere in the company — or beyond — through an easily-created virtual data access layer. Once accessed, data can easily be aggregated through a combination of reusable queries and views that are maintained in the DSP server.

Query Development. Then, once the data is collected under a single point of access, it is not difficult to create query functions that consolidate data from these disparate sources and present a common, reusable view ready for more specialized queries.

The declarative form of DSP artifacts (query functions in data services) makes them very readable.

Query Deployment. Once developed, queries are easily integrated into a client application thorough a variety of access methods such as the DSP Mediator API, a data service control, JDBC, or SQL.

Integration. Business logic for the RTLApp is provided by the NetUI and page flow features of Workshop. However, DSP query functions could have as easily been integrated and maintained within the business logic of any J2EE application.

## Purpose of the Avitek RTLApp

The RTLApp is designed to illustrate how DSP-generated queries can aggregate data from potentially highly disparate data sources, allowing access to that data through a single point of access that itself is easily integrated with the application.

Note: To simplify the running of the RTLApp, the multiple data sources described in this document are simulated using the PointBase RDBMS which is shipped with DSP. In the original implementation, these databases were represented by major vendor RDBMS systems.

## Finding the Components

The RTLApp is located in the following directory:

>     <WL_HOME>/samples/domains/liquiddata/RTLApp

RTLApp controls, pages, processes, and resources used to create the SampleApp can be found at:

>     <WL_HOME>/samples/domains/liquiddata/RTLSelfService

Some of the schemas used in the RTLApp are in the following directory:

>     <WL_HOME>/samples/domains/liquiddata/schemas

Others are located in their respective data service.

The Workshop `.work` file for the SampleApp is located at:

>     <WL_HOME>/samples/domains/liquiddata/RTLApp/RTLApp.work

When you install DSP with the WebLogic Platform, the source code for the RTLApp can be accessed from Workshop. For instructions, see Viewing RTLApp Source.

For additional information and references, see:

- Running Retail Sample Application in a Browser.
- Using Workshop Controls to Develop Data Service Platform Applications in the Application Developer's Guide for the specific steps required to create the data service control.

## Analyzing the RTLApp Architecture

Several BEA technologies are exercised by the RTLApp.

- Query Development. Data services and queries that draw data from multiple data sources are created in WebLogic Workshop.
- Query Access. Query functions are accessible through the DSP mediator API, JDBC, and the Workshop data service control and can be tested within Workshop.
- Client-side Development. Workshop also provides an environment for building application logic through NetUI, page flow, and other technologies.

### Available Data Sources

Although the RTLApp is very simple, the underlying data acquisition is challenging because date comes from four heterogeneous data sources. These are:

- Customer Relationship Management (CRM) system. CRM data (customer and credit card information) is stored in a database called RTLCUSTOMER.
- Order Management System (OMS). Avitek has two order management systems:

- Apparel products. Information is maintained on site in a second database. This is represented in DSP as RTLAPPLOMS.
- Electronic products. OMS information is available from a legacy system (RTLELECOMS) via a web service. The web service has several methods such as getCustomerOrderByCustomerID(), that takes a customer ID as input and returns a list of customer open order information through a web service.

- Customer Service. Service data is stored in a third database. The schema for this data is RTLSERVICE.
- Billing information. Credit card information is maintained in a separate, highly secure database, RTLBILLING.

### Retail Sample Application Queries

The following section describes work done by some of the RTLApp data services.

#### Physical Data Services

There physical data services correspond with the physical data sources needed by the application.

- ApparelDB includes the following data services: CUSTOMER_ORDER, CUSTOMER_ORDER_LINE_ITEM, and PRODUCT.
- BillingDB includes a CREDIT_CARD data service.
- CustomerDB includes ADDRESS and CUSTOMER data services.
- ElectronicsWS includes data services based on the web services. The data services include: getCustomerOrderByCustomerID, getCustomerOrderByOrderID, and getProductList.
- ServiceDB is the source for the SERVICE_CASE data service.

In RTLApp physical data services typically have a read function and, often, one or several navigation functions that correlate to the primary key/foreign key relationship between relational sources.

#### Logical Data Services

Logical data services (services based on physical data services or other logical data services) are located in a folder called RTLServices. It is in these logical data services that read and navigation functions drawing on multiple data sources are developed and maintained.

### Avitek Customer Self-Service Sample Application

Table 5-1 shows the relationship between the data sources, major data elements (for RDBMS systems: tables and columns), sample application JSPs, and the RTLApp web pages.

Table 5-1

Application Page | Data Sources | Primary Data Objects | JSP
--- | --- | --- | ---
Profile page | Customer Relationship Management (CRM) RDBMS (Oracle) Credit card data (Sybase) | from RTLServices/Customer Customer profile Bill-to, ship-to address from RTLServices/CreditCard Credit card information | `ProfileView.jsp`
Open Orders page | Customer Relationship Management (CRM) RDBMS Order Management System (OMS) RDBMS OMS via a web service | from RTLServices/Customer CustID, name from RTLServices/ApplOrder Order summary information from RTLServices/ApplOrderDetailView Order detail information from RTLServices/ElecOrder Order summary information from RTLServices/ElecOrderDetailView Order detail information | `DefaultView.jsp`
Support | For apparel order detail: Order Management System (OMS) RDBMS Customer Relationship Management (CRM) RDBMS For electronics order detail: OMS via a web service Customer Relationship Management (CRM) RDBMS | from RTLServices/Customer: CustID, name For customer support cases: case status | `caseView.jsp`
Order History page | Same as Open Orders page | Same as Open Orders page | `OrderHistory.jsp`
Search page | Same as Open Orders page | from RTLServices/ApplOrder Description Order date Order amount from RTLServices/ElecOrder Description Order date Order amount | OrderSearch.jsp

RTLApp Primary Pages and Their Data Sources, Primary Data Elements, and Associated JSPs

# Running Retail Sample Application in a Browser

If you have not already done so, use Quick Start Instructions for the Avitek Sample Application (RTLApp) to start Retail Sample Application. You can choose from users Steve, Jack, Tim, Homer, or Jerry. Each uses the password `weblogic`.

Once a customer logs in, she or he sees their MyProfile screen. From there he or she can navigate to information on open orders, order history, support, search, and logout. Customers can edit open orders (see Figure 5-4) and get details on completed orders. Search allows the user to supply product description information, start or end date, or order amount brackets.

The application also demonstrates some DSP facilities including the ability to:

- Refresh data
- Restrict or unrestrict access
- Make a data source unavailable
- Enable Cache
- Show SQL reports created from Crystal Reports
- Update data

### My Profile Page in RTLApp

The My Profile page illustrates DSP's ability to perform automatic read/write on distributed data.

Figure 5-3 My Profile Page

My Profile page consolidates Customer and Credit Card information. Users can change their personal profile information, address information, and credit card information. Changes are initially reflected on their MyProfile page. If satisfied, the user can click Submit All Changes to persist changes to the respective data sources.

#### Page Design

The page is based on `ProfileView.jsp` and the ProfileView data service (`ProfileView.ds`).

### Open Order Page in RTLApp

The RTLApp Open Order page consolidates a customer's electronics and apparel open orders.

Figure 5-4 RTLApp Open Order Page

#### Data Sources

From the user's perspective, changing data is simply a matter of select and type. However, the underlying update mechanisms for electronic orders (which are maintained as a web service) and apparel orders are quite different.

#### Update Mechanisms

Electronic orders are derived from a web service. In this case, updating a electronic order demonstrates web service custom update capabilities.

Apparel orders are derived from a relational database and updates are automatic.

#### Caching Options

The Enable Cache option turns on caching for the function underlying the Open Orders page. You can use the Refresh button to verify that the execution time when cache is enabled is significantly faster than when it is not.

#### Handling Unavailable Sources

Click the Make Electronics Source Unavailable button to disable the web service. This action also refreshes your Open Orders page. Notice that you can still retrieve partial results (apparel orders) when a data source becomes unavailable.

#### Access LD via JDBC

The Show SQL Report button illustrates accessing data through JDBC. This demonstrates the integration of DSP query functions with reporting and business intelligence tools such as Crystal Reports.

#### Page Design

The Open Order page is controlled by a JSP named `defaultView.jsp`. Call-outs in Figure 5-4 show underlying data sources. The page derives its font and other look-and-feel characteristics from a cascading stylesheet.

### Order History in RTLApp

The RTLApp Order History page displays historical order information for electronic and apparel orders.

Figure 5-5 RTLApp Order History Page

Users have several options associated with viewing their previous orders:

- Items can be ordered by date, amount, or order type (electronic or apparel).
- A operational filter can be applied based on order amount.
- The user can restrict the number of orders retrieved to a pre-set amount (5, 10, 15, 20, or all).
- The user can restrict orders to apparel or electronic.

An Apply button is provided to control page refresh.

#### Security

DSP security can be demonstrated when the number of orders is set to All. Then when the Restrict Access option is selected, data is automatically redacted to show only orders where order amounts are less than $500.00.

#### Page Design

The Order History page is controlled by a `orderHistory.jsp`.

### Support Page in RTLApp

The Support page provides information on any open support cases for the currently logged-in customer.

Figure 5-6 RTLApp Customer Support Page

The underlying JSP is `CaseView.jsp`.

### Search Page in RTLApp

Users can search for specific orders based on order dates, items, or amounts. The underlying code executes ad hoc DSP query functions.

Figure 5-7 RTLApp Search Page

Users can search on any combination of search field criteria including product description, start or end data, and a range of order amounts.

The JSP for this page initiates a small Java program that incorporates customer input and generates an XQuery based on the selected parameters.

# Viewing RTLApp Source

The data services, functions, JSP pages, and connection logic for the RTLApp were created in Workshop. You can view the source for the RTLApp in Workshop as well.

To open the RTLApp application, open the `RTLApp.work` file in Workshop. The full path is:

>     <WL_HOME>/samples/domains/liquiddata/RTLApp/RTLApp.work

Note: If you are already running WebLogic Workshop or have previously run it with a different server setting, you may need to change your application server properties settings. If necessary, select the following from the WebLogic Workshop menu:

Tools`` —>`` Application Properties`` —>`` WebLogic Server

When opening the RTLApp in WebLogic Workshop, you initially see the application components and the work area.

Figure 5-8 Initial Retail Sample Application Initial Project View

WebLogic Workshop allows you to work with the application you have under development as components or files. Web pages can be displayed and run, page flows and application logic can be developed and tested.

Note: Getting Started with WebLogic Workshop fully describes the IDE and how it can be used to build enterprise applications. The on-line document includes numerous examples and tutorials.

The WebLogic Workshop Samples application contains a number of samples relevant to data access and XML. See:

<WL_HOME>/samples/workshop/SamplesApp/`SamplesApp.work`

## WebLogic Workshop Components of the RTLApp

Like all WebLogic Workshop applications, components of the RTLApp are arranged in folders. This section briefly describes some of these folders and their contents.

### Data Services Folder

The Data Services folder contains both physical and logical data services.

Figure 5-9 Major Components of the RTLApp DataServices Folder

Physical data services, which are based on physical data sources, include apparel orders (ApparelDB), electronic orders (ElectronicsWS), credit card information (BillingDB), and customer service information (ServiceDB). Logical data services are all grouped in the RTLServices folder.

Model diagrams based on both physical and logical data services are contained in the MODELS folder. Of particular interest is the EnterpriseDataModel, which models all the physical data services in the application. Logical model diagrams include the RTLApp model, which summarizes the data service relationships that make up the RTLApp.

Note: The DataServices/Demo directory contains simple examples of delimited file data, XML file data, and Java functions being used as the basis for data services.

### ElecWS Folder

The ElecWS folder contains the web service that serves as the basis for the electronics orders data service used by RTLApp.

### RTLSelfService Folder

Many of the building blocks of the Retail Sample Application are available from the RTLSelfService folder.

Figure 5-10 Major Components of the RTLApp RTLSelfService Folder

The following components are of special interest:

- Controls folder. The Controls folder the RTLApp contains the `RTLControl.jcx` file. This is a file generated by the data service control that contains methods for each query function used in the DSP application. In Design View each function is listed. Clicking on a name switches you to Source View where you can see details about the function including:

- Qualified name (qname) of the function's data service
- Function name
- Schema URI
- Schema root element
- Function call and parameters

For additional information on the RTLControl see Controls.

- cryistalreportviewers10 folder. Contains files related to Crystal Reports 10.
- ld_conceptual_files folder. Contains conceptual information about DSP that appears at the bottom of some of the RTLApp pages.
- Pages folder. Contains the JSPs and the page flow controller, `demoPageFlowController.jpf`, that make up the RTLApp web application.

For additional information on the pages see Application Pages.

- Resources folder. Contains common resources such as the HTML style sheet, graphics files and common JSPs such as headers and footers.
- SQLReport_files folder. Contains files related to SQL reports that can be generated through applications such as Crystal Reports.
- WEB-INF folder. Contains application source components, in particular struts and NetUI components that come with WebLogic Workshop.

### Schemas

The Schemas folder contains schemas developed for some logical data services and associated XML Bean classes.

## Controls

The RTLControl contains automatically-generated methods based on a set of stored queries selected by the developer of the data service controls. For information on accessing DSP queries in WebLogic Workshop see the section "Select Data Service Functions to Add to a Control" in Accessing Data Services from Workshop Applications in the Application Developer's Guide.

Figure 5-11 Design View of RTLControl Design View

A portion of the Source View of the `RTLOrderSummary` method of the `RTLControl.jcx` file is shown in Figure 5-12. Note that the name of the target schema for the query appears in comments.

Figure 5-12 Source view of a Data Service Control

.

Each method in the data service control corresponds to a query function. Each method returns an XMLBean type. The XMLBeans are generated when the control is created, and are stored in the Libraries directory of the WebLogic Workshop application.

## Application Pages

In the Pages folder you can find the Java Server Pages (JSPs) that make up the RTLApp. These were constructed in WebLogic Workshop using queries RTLControl and NetUI graphical elements.

Figure 5-13 JSP Pages in the RTLApp

### Application Logic: Page Flow

The RTLApp is composed of java server pages (JSPs) that are managed by a WebLogic Workshop PageFlowController. The PageFlowController is named`demoPageFlowController.jpf`.

From an application logic perspective, whenever a user releases control of a page by selecting an option such as Next, Previous, Ok, Cancel, and so forth, application logic returns to the PageFlowController. Once that logic is processed, the user sees the appropriate web page.

Using WebLogic Workshop you can inspect, change and extend page flow programmatically or graphically. There are three views of page flow: Flow View, Action View, and Source View.

#### Page Flow: Flow View

The Workshop page flow schematic (Figure 5-14) illustrates graphically the relationship between JSPs, including has modeless page flow is determined by user actions.

When you click on a particular page name, the page opens in the WebLogic Workshop development browser.

Figure 5-14 Retail Sample Application Page Flow

The three primary elements found in Page Flow View are:

- Pages. Clicking on a particular page will open the page for editing.
- Actions. The transition between pages is controlled by actions. Specific actions are user-driven such as in the case of a user accepting an option ("OK") or deciding against it ("Cancel") via a particular form or dialog box.
- Source. When source is selected, the code for the page appears in the work area.

#### Page Flow: Action View

The Action View tab helps in finding the location of page flow actions associated with the RTLApp.

Figure 5-15 RTLApp Action View

Clicking on an action items opens demoPageFlowController to the relevant section of code.

#### Page Flow: Source View

The PageFlowController file contains several parts:

- Declarations of graphical elements in the application.
- Public transient simple and array variables that facilitate and persist application logic between pages.
- `@jpf:forward` calls within comments that associate user actions with appropriate target JSPs.
- Queries and associated logic.

# Summary

In summary, the RTLApp provides:

- A virtual data access layer that allows you to treat heterogeneous data as from a single source.
- Ability to access the data through declarative queries that can be created in the XQuery Editor or developed externally.
- Availability of DSP queries and server for easy integration into applications or processes.

# Where To Go From Here

Here are some additional resources for learning more about Data Services Platform and WebLogic Workshop:

- The Data Services Platform Concepts Guide provides a comprehensive overview of DSP technology.
- The Building Queries and Data Views explains how to create the data services, model diagrams, and query functions that are called by client applications.
- The Application Developer's Guide describes the several ways that client applications can access DSP read-write query functions.
- To learn more about WebLogic Workshop see Getting Started with WebLogic Workshop.
- To learn more about XML Beans see Getting Started with XML Beans.
- The WebLogic Workshop Samples application installed with WebLogic Platform contains a number of samples relevant to data binding and XML. See:

<WL_HOME>/samples/workshop/SamplesApp/`Samples.work`