Project Notes
Project: Application: Cliffhanger Adventure Gear
Author:
Application Methods, Inc.
Description
This sample application is an example of an order entry system for a fictitious
company selling outdoor adventure gear. The company, Cliffhanger Adventure
Gear, requires a system to manage order, customer, and product inventory
information for their business. They sell products via mail order and also have
a chain of stores. This application helps them track customer information and
record orders for equipment from their mail order customers, as well as their
store customers who wish to order items that may not be available in the store
they visit. This application also supports a set of common business
rules, illustrating how to create a client/server application using JBuilder's
DataExpress database components.
Two related applications share the Cliffhanger database:
-
CreditCardApproval: an example of a credit approval/credit card
issuing system. The sample consists of two JBuilder projects, a Credit Approval
Server application and a Credit Approval Client applet/application. The Credit
Approval Server and Client communicate by means of a set of CORBA objects,
illustrating how to create and use CORBA objects in JBuilder.
-
OrderTracker: a simple illustration of a database-aware applet,
OrderTracker displays the status of an order created through the Cliffhanger order
entry application.
Setup
This sample stores its data in InterBase databases. To run it, you must
Running the Sample
To run this sample,
-
Start InterBase and InterServer.
-
Select Run | Run project from the main menu.
The Cliffhanger sample also includes Order Tracker, a simple illustration
of a database-aware applet. This applet allows a user to retrieve status
information about an order created through the Cliffhanger order entry
application. Order Tracker shares data with the Cliffhanger application, but resides
in a separate directory. Refer to the project notes in
samples/OrderTracker/OrderTracker.html
for more information.
The following project notes are divided into discussions of the features
demonstrated in the main functional areas of the application, including the
Data Module. The main functional areas are as follows:
Data Module
The DataModule1 class in the Cliffhanger project implements the DataModule
interface that contains the Database component, all the
QueryDataSet components, and all the client business rules logic.
Data modules simplify reuse and multiple use of collections of dataset
components.
The DataModule1 class demonstrates the following features:
- Connecting to the sample InterBase database, cliffhanger.gdb, using the
Database and QueryDataSet components via JDBC. (See the
"Connecting to a database using JDBC" and "Querying a database" topics in the
Developing Database Applications help topic).
- Using QueryDataSet components to get record sets used throughout
the application and, in many cases, used in multiple frame classes.
- Using the MasterLink property of a QueryDataSet
component to establish master-detail relationships between datasets.
- Use of persistent columns, which are columns where structural or display
information is specified as column properties. Persistent columns offer the
following advantages:
- Performance benefits, because column structure information does not
need to be obtained from the server.
- Formatting of data displayed using display masks; e.g. dates, credit
card numbers, and currency values.
- Data editing controlled by using edit masks; e.g. dates, and credit card
numbers.
- Calculated columns that get their value as a result of evaluating an
expression or executing a lookup into another table; e.g. an order item
record only stores the ProductID, but a calculated column is used to display
the description of the product.
- Aggregate columns that get their value as a result of a calculation on
groups of columns to aggregate on. We have used a simple sum aggregate for
the SubTotal of an order, and then used a CalcAggFieldsListener to calculate
the Tax, Shipping and Amount Due.
- Column-level validation using the Column.Validate event.
- Column initialization with default values when inserting new rows.
- Row-level validation using DataSet.EditListener events to validate the data
for an entire row before posting the inserted or updated row.
- Using explicit QueryResolver components to customize resolution behavior,
wiring ResolverListener events on the QueryResolvers to allow the application
to handle error events for insert, update and delete operations. There is an
example of retrying an update of the Product table in the UpdateError event
handler.
- Includes event handlers for the various StorageDataSet.EditListener events,
such as DataSet.modifying, adding, deleting etc.. For example, we prompt the user
to confirm deletes in the DataSet.deleting event handler.
Splash screen
The Splash screen is implemented by the SplashScreen class. The project
demonstrates how to create a splash screen that is shown while the application
is loading and establishing the connection to the database. Refer to code
comments in the source code files CliffhangerApplication.java and
SplashScreen.java.
Main Menu screen
The Main Menu screen is implemented by the MainFrame class. This screen is the
main window of the application from which the user can view, create and modify
order, customer, product and category records.
The MainFrame class demonstrates the following features:
- A custom menu that was created by selecting the "Generate menu bar"
option in the Application Wizard when first creating the application framework.
- An about box that was created by selecting the "Generate about box"
option in the Application Wizard when first creating the application framework.
- Pop-up menus to navigate to different areas of the application. This
shows how to display and interact with other frames in the application.
- Graphic images in buttons.
- A label that displays hints when the mouse cursor is placed over the buttons on the frame.
Order Entry screen
The Order Entry screen is implemented by the OrderEntryFrame class. This screen
allows the user to add a new order record, modify or delete existing orders.
Each order has several order items. This screen is the most complicated in the
application, hence it demonstrates some of the robust application features that
can be built with JBuilder.
The OrderEntryFrame class demonstrates the following features:
- Displays a master-detail view of two QueryDataSets,
orders and order items. The OrderEntryFrame shows how to use the data module
to obtain the required QueryDataSet instances and how to link the
data-aware controls to the datasets.
- Displays a JdbNavToolBar that is used to navigate through the
records of the Orders dataset.
- Includes the use of a modal AddCustomerDlg dialog to add a new customer from
the Orders screen and use the new customer for the current order. Similarly, a
modal FindOrderCustomer dialog is used to find a customer for the current order.
- Includes functionality to copy the Ship To information of the current order
to the default shipping information stored in the customer record.
- Includes a Save button that posts edits than have not already been posted
and resolves the changes to the database. Also includes a Cancel button that
cancels edits which have not been posted.
- Includes JdbComboBoxes that are populated by lookup datasets.
- Contains a JdbTable which displays order item data. The
JdbTable also demonstrates:
- Formatting displayed data using display masks for currency columns.
- Calculated columns; e.g. ProductName and ExtendedPrice.
- Use of a pick list that displays multiple columns from the lookup table
and stores values from multiple columns of the lookup table back into
the table being edited. The ProductID column illustrates this
technique.
- Includes two JdbStatusLabels that are linked to the master
dataset and the detail dataset. These automatically display navigation
information and data validation messages generated by the dataset components.
- Demonstrates prompting the user to save pending changes before closing the
window.
- Demonstrates resolving QueryDataSets linked in a master-detail
relationship using the Database.saveChanges() method.
Customer maintenance screen
The Customer maintenance screen is implemented by the CustomerFrame class. This
screen allows the user to add new customer records and modify or delete
existing customers. This screen also uses a grid to display all the order records
for the current customer. The user can view the details of a particular order,
and create a new order for the current customer.
The CustomerFrame class demonstrates the following features:
- Displays a master-detail view of two QueryDataSets,
Customer and Orders. The CustomerFrame shows how to use the data module
to obtain the required QueryDataSet instances, and linking the
data-aware controls to the datasets.
- Includes a JdbNavToolBar to navigate through the Customer records.
- Demonstrates using another frame, the OrderEntryFrame, to view a customer's
order and to add a new order for the current customer.
- Like the OrderEntryFrame, demonstrates prompting the user to save pending
changes before closing the window, and demonstrates resolving
QueryDataSets linked in a master-detail relationship using the
Database.saveChanges() method.
Product maintenance screen
The Product maintenance screen is implemented by the ProductFrame class. This
screen allows the user to add new product records and modify or delete
existing products.
The ProductFrame class demonstrates the following features:
- Includes a JdbNavToolBar that is used to navigate through
the product records.
- The ProductFrame shows how to use the data module to obtain the required
QueryDataSet instances, and linking the data-aware controls
to the datasets.
- Includes a JdbComboBox populated by a lookup dataset.
- Includes a JCheckBox linked to a boolean field.
- Includes a JdbStatusLabel linked to the Product dataset. Hooking
the dataset to a status bar results in automatic display of record navigation
information and data validation messages generated by the associated dataset
component.
- Like the OrderEntryFrame, demonstrates prompting the user to save pending
changes before closing the window. Also demonstrates resolving the
QueryDataSet using the Database.saveChanges() method.
Category maintenance screen
The Category maintenance screen is implemented by the CategoryFrame class. This
screen allows the user to add a new category record, and modify or delete
existing categories.
The CategoryFrame class demonstrates the following features:
- Includes a JdbNavToolBar used to navigate through
the category records.
- The CategoryFrame shows how to use the data module to obtain the required
QueryDataSet instances, and linking the data aware visual controls
to the datasets.
- Includes a JdbTable which displays the category records.
- Includes a JdbStatusLabel control that is linked to the product dataset.
This automatically displays navigation information and data validation messages
generated by the dataset component.
- Like the OrderEntryFrame, demonstrates prompting the user to save pending
changes before closing the window. Also demonstrates resolving the
QueryDataSet using the Database.saveChanges() method.
Find dialogs
The FindFrame class is a base class from which other Find dialogs are
inherited. The other Find dialogs are OrderFindFrame, ProductFindFrame,
and CustomerFindFrame. They are used to browse or find a particular order,
product or customer record respectively. All the Find dialogs have similar
appearance and behavior. The inherited classes set FindFrame
properties to customize appearance and behavior.
The FindFrame class demonstrates the following features:
- Use of the JdbNavField which allows the user to do an
incremental search for a row having the value entered. The search column is
determined by the selected item in a JdbComboBox that lists the
available columns for the search.
- Includes a JdbTable that highlights the row found by the
incremental search.
- Includes a JButton that brings up the appropriate frame to
display the selected record.