This tutorial describes how to develop a sample database application using
DataExpress components and the JBuilder design tools. Where necessary, the code generated by the design tools will be modified to provide custom behavior.
This application demonstrates the following functionality:
■ Connects to the JDataStore sample database, employee.jds, using the Database and QueryDataSet components. (See Chapter 4, “Connecting to a database” and
“Querying a database” on page 46.)
■ Contains a JdbTable which displays the data while also demonstrating the following features:
■ Persistent columns, which are columns where structure information typically obtained from the server is specified as a column property instead. This offers performance benefits as well as persistence of column-level properties. (See
“Persistent columns” on page 73 for more information on this feature.) In the designer, double-click the data set to open the column designer to view more information on each column.
■ Formatting of the data displayed in the JdbTable using display masks (the HIRE_DATE column). (See “Adding an Edit or Display Pattern for data formatting” on page 148.)
■ Data editing that is controlled using edit masks (the HIRE_DATE column). (See
“Adding an Edit or Display Pattern for data formatting” on page 148.)
■ Calculated and aggregated fields which get their values as a result of an expression evaluation (the NEW_SALARY, ORG_TOTAL, NEW_TOTAL, DIFF_SALARY, AND DIFF_TOTAL columns). (See “Using calculated columns”
on page 142.)
T u t o r i a l : C r e a t i n g a b a s i c d a t a b a s e a p p l i c a t i o n
■ Includes a JdbStatusLabel control that displays navigation information, data
validation messages, and so on. Messages are written to the JdbStatusLabel control when appropriate, or when instructed programmatically. (See “Displaying status information” on page 158.)
■ Displays a JdbNavToolBar for easy navigation through the data displayed in the table.
■ Lets you locate data interactively using a JdbNavField which is embedded in the JdbNavToolBar. For more information on locating data, see “Locating data” on page 130.
■ Uses a DBDisposeMonitor to automatically close the database connection when the frame is closed.
■ Resolves changes made to the data in the QueryDataSet by using default resolver behavior. (See “Understanding default resolving” on page 87.) The Save button of the JdbNavToolBar performs the save. Messages regarding the resolve process are displayed in the JdbStatusLabel control.
For this tutorial, you will perform the following tasks:
■ Create a JBuilder project
■ Generate an application
■ Add DataExpress components to access data from the database
■ Design the columns for the application
■ Add dbSwing components to create a user interface
■ Aggregate data with calculated fields
When you have completed the tutorial, your application will look like this:
Figure 17.1 Basic database application
C h a p t e r 1 7 : T u t o ri a l : C r e a t i n g a b a s i c d a t a b a s e a p p l i c a t i o n 187 S t e p 1 : C r e a t i n g t h e p r o j e c t
The completed application can be viewed by opening the sample project file, BasicApp.jpx, in <jbuilder>/samples/DataExpress/BasicApp/. There may be minor differences between the application created in this tutorial and the sample application.
For users with read-only access to JBuilder samples, copy the samples directory into a directory with read/write permissions.
See the Tutorials section in the JBuilder Quick Tips for useful information about viewing and printing tutorials. The Accessibility options section in the JBuilder Quick Tips contains tips on using JBuilder features to improve JBuilder’s ease of use for people with disabilities.
For information on documentation conventions used in this tutorial and other JBuilder documentation, see “Documentation conventions” on page 6.
Step 1: Creating the project
To develop your database application in JBuilder, you first need to create a new project. To do this,
1 Choose File|New Project to display the Project wizard.
2 Type BasicApp in the Name field.
3 Click Finish to close the Project wizard and create the project. You do not need to make any changes to the defaults on Steps 2, 3, or 4 of the wizard.
The project file BasicApp.jpx is displayed in the project pane.
Step 2: Generating an application
The Application wizard creates .java source files that are added to the project you just created.
To generate source files for your application using the Application wizard, follow these steps:
1 Choose File|New|General to open the General panel in the object gallery.
2 Double-click the Application icon to open the Application wizard.
3 In Step 1 of the Application wizard, accept the default package name, basicapp, type BasicApp in the Class Name field, and click Next.
Note The package name used in this tutorial, basicapp, differs from the package name used in the sample application, com.borland.samples.dx.basicapp, but the applications are otherwise the same.
4 In Step 2 of the Application wizard, type BasicAppFrame in the Class field, type Sample Database Application in the Title field, and click Finish.
The new Java source files are added to your project and displayed as nodes in the project pane. The source code for BasicAppFrame.java is open in the content pane.
5 Choose File|Save All to save the source files and the project file.
S t e p 3 : A d d i n g D a t a E x p r e s s c o m p o n e n t s t o y o u r a p p l i c a t i o n
Step 3: Adding DataExpress components to your application
The UI designer is used to add the DataExpress components to BasicAppFrame.java.
You will add the following DataExpress components to your application:
■ Database
■ QueryDataSet
■ DBDisposeMonitor
These components provide the underlying database framework for the application.
1 Select the Design tab for BasicAppFrame.java in the content pane to activate the UI designer.
The component palette appears on the side of the UI designer.
2 Select the DataExpress page of the component palette, click the Database component, and then click in the structure pane or the UI designer to add the component to the application.
The new Database component, database1, shows up under the Data Access node in the structure pane, and the following line of code is added to the Frame class:
Database database1 = new Database();
3 Select the database1 component in the structure pane, select the connection property in the Inspector, and click the ellipsis (…) button to open the Connection dialog box.
4 Set the connection properties to the JDataStore sample employee table, using the field values in the following table.
The Connection URL points to the employee.jds file in a subdirectory of your JBuilder installation directory, <jbuilder>.
The Connection dialog box includes a Test Connection button. Click this button to check that the connection properties have been correctly set. Results of the connection attempt are displayed in the status area. When the connection is successful, click OK. If the connection is not successful, make sure you have followed all the steps for Chapter 4, “Connecting to a database.”
5 Select the DataExpress page of the component palette, click the QueryDataSet component, and then click in the structure pane or the UI Designer to add the component to the application.
The new QueryDataSet component, queryDataSet1, shows up under the Data Access node in the structure pane, and the following line of code is added to the Frame class:
QueryDataSet queryDataSet1 = new QueryDataSet();
6 Select the query property of the QueryDataSet component in the Inspector, click the ellipsis (…) button to open the Query dialog box, and set the following properties:
Property name Value
Driver com.borland.datastore.jdbc.DataStoreDriver
URL Browse to your copy of <jbuilder>/samples/JDataStore/
datastores/employee.jds
Username Enter your name (the default is “SYSDBA”) Password Enter your password (the default is “masterkey”)
Property name Value
Database database1
SQL Statement SELECT EMP_NO, FULL_NAME, HIRE_DATE, DEPT_NO, JOB_COUNTRY, SALARY FROM EMPLOYEE
C h a p t e r 1 7 : T u t o ri a l : C r e a t i n g a b a s i c d a t a b a s e a p p l i c a t i o n 189 S t e p 3 : A d d i n g D a t a E x p r e s s c o m p o n e n t s t o y o u r a p p l i c a t i o n
The SQL Statement will be run against the specified Database automatically when the QueryDataSet is opened.
7 Click Test Query to ensure that the query is runnable.
The Query dialog box should look like this to indicate the query was successful.
Figure 17.2 Query dialog box
If the Query dialog box indicates Fail, review the information you have entered in the query for spelling and omission errors.
8 Click OK to close the Query dialog box.
9 Select the More dbSwing page of the component palette, click the DBDisposeMonitor component, and click in the structure pane to add the component to your
application.
The new DBDisposeMonitor component, dBDisposeMonitor1, shows up under the Data Access node in the structure pane, and the following line of code is added to the Frame class:
DBDisposeMonitor dBDisposeMonitor1 = new DBDisposeMonitor();
The DBDisposeMonitor will close the JDataStore when the window is closed.
10 Set the dataAwareComponentContainer property for the DBDisposeMonitor to this.
11 Expand the queryDataSet1 node in the structure pane.
Figure 17.3 queryDataSet1 node expanded
The selected columns of the sample JDataStore Employee database, employee.jds, are displayed in the queryDataSet1 node.
You now have the basic components in place for retrieving and storing data from the Employee database. Next, you will create a user interface for displaying and editing the data.
S t e p 4 : D e s i g n i n g t h e c o l u m n s f o r t h e a p p l i c a t i o n
Step 4: Designing the columns for the application
Before we add a user interface to the application, we will,
■ Add new columns and edit existing columns
■ Specify a calculation for the calculated columns