Project Notes

Project: 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 chain of stores. The application will help 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 visited. The sample application will support a set of common business rules, illustrating how to create a client/server application using JBuilder's DataExpress database components.

Setup
To run this sample, you must

Use a version of JBuilder that includes the JBuilder DataExpress database architecture components.
Note: All versions of JBuilder provide direct access to SQL data through the JavaSoft JDBC API. Some versions of JBuilder provide additional DataExpress components (on the Data Access tab of the Component Palette) that greatly simplify RAD visual development of database applications. Refer to the JBuilder product page from the Borland Web site for availability of features in each JBuilder version.
Have Local InterBase and the Visigenic ODBC driver for InterBase installed. Local InterBase can be installed from the main JBuilder Client/Server installer. Within the InterBase installation, there is an option to install the ODBC driver.
Define an ODBC data source. The Cliffhanger application includes in its data subdirectory an InterBase database called CLIFFHANGER.GDB. To define an ODBC data source called "Cliffhanger" that points to it:
- Launch "32bit ODBC" from the Windows Control Panel
- Click the Add button
- Select the Visigenic InterBase driver and click Ok
- Set Data Source Name to "Cliffhanger"; set Database to the fully-qualified name of the database (usually C:\JBuilder\samples\borland\reference\cliffhanger\data\CLIFFHANGER.GDB"); set Username to "SYSDBA"; and set Password to "masterkey"
- Click Test Connect. Correct the information entered if necessary; when it's okay, click Ok and close the Data Sources dialog.

Other documentation and data files
Two other documents are included in this project. One highlights some of the reusable code snippets from the Cliffhanger application that might be useful for your own JBuilder projects. The other is a tutorial on how to recreate the master-detail relationship used in the CustomerFrame. This may be helpful in showing you how to create your own master-detail forms with JBuilder.

Also, the Cliffhanger sample 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\borland\reference\tracker for more information.

In addition to the InterBase database CLIFFHANGER.GDB, this application's data directory contains two text files, db.sql and DataStock.sql, that can be used to generate a clean copy of the database. To use them:

First, be sure you want to discard the existing CLIFFHANGER.GDB database. If you don't, move it to a safe place before continuing.
Run the "InterBase Windows ISQL" tool from the InterBase program group.
Choose File | Run an ISQL Script.
Navigate to db.sql and select it.
Choose to save output to a file, and supply a name.
Check that there are no errors, then run the DataStock.sql script in the same way.
This will create a new CLIFFHANGER.GDB in the directory that db.sql and DataStock.sql are in and fill it with sample data.

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
Splash screen
Main Menu screen
Order Entry screen
Customer maintenance screen
Product maintenance screen
Category maintenance screen
Find dialogs

Data Module
The DataModule1 class in the Cliffhanger project implements the DataModule interface that contains the Database/EM> 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 Database Application Developer's Guide)

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.
olumn 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 SplashFrame 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 SplashFrame.java.
Main Menu screen
The Main Menu screen is implemented by the MainFrame1 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:

Includes a custom menu that was created by selecting the "Generate menu bar" option in the Application Wizard when first creating the application framework.

Includes an about box that was created by selecting the "Generate about box" option in the Application Wizard when first creating the application framework.

Includes pop-up menus to navigate to different areas of the application. This shows how to display and interact with other frames in the application.

Includes the use of graphic images for Button controls and Image controls.

Includes a StatusBar control that displays hints when the mouse cursor is placed over the Button controls 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 NavigatorControl that is used to navigate through the records of the Orders dataset. There is code to disable certain navigator buttons at run time.

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 ChoiceControls that are populated by lookup datasets.

Contains a GridControl which displays order item data. The GridControl 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.
An item editor: in order to display multiple columns in a pick list, we instantiate a PopupPickListItemEditor and set the ProductID column's itemEditor property to it.

Includes two StatusBar controls 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 NavigatorControl 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 NavigatorControl 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 ChoiceControl populated by a lookup dataset.

Includes a CheckBoxControl linked to a boolean field.

Includes a StatusBar control 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 NavigatorControl 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 GridControl which displays the category records.

Includes a StatusBar 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 override some of the frame properties and methods to customize appearance and behavior.
The FindFrame class demonstrates the following features:

Use of the LocatorControl 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 ChoiceControl that lists the available columns for the search.

Includes a GridControl that highlights the row found by the incremental search.

Includes a ButtonControl that brings up the appropriate frame to display the selected record.