An introductory database tutorial using a text file

This introductory tutorial creates an application that reads data from a text file, and steps through building the user interface (UI) for the application using JBuilder design tools. Then it explores the JBuilder DataExpress architecture and applies database concepts to the tutorial even though this application does not connecting to a true database.

The UI consists of three controls: a grid control that displays the data from the text file, a navigator to aid in browsing through the data, and a status area that displays messages.

The basic steps to completing this sample application are

  1. "Creating the application structure" describes using the Project and Application wizards to create the basic application files.
  2. "Adding UI components to your application" explains how to add the GridControl and NavigatorControl to your application.
  3. "Adding DataExpress components to your application" explains how to add the TableDataSet and TextDataFile components which do not have a visual representation at run time.
  4. "Setting properties to connect the components" describes how to get the components "talking" to each other by setting the appropriate properties.
  5. "Compiling, running, and debugging your program" explores getting your application to run and do what you want it to do.

When you have completed the tutorial, your application will look like this:

You can see the code for the completed tutorial by opening the sample project file samples\borland\samples\tutorial\dataset\TextDataFile\TextDataFile.jpr of your JBuilder installation.

Creating the application structure

Let's start by creating the application using the Project and Application Wizards. To start the Project Wizard,

  1. Choose File|Close All from the JBuilder menu to close any existing projects.
  2. Choose File|New Project to start the Project Wizard.
  3. Keep the specified path, and change the default project name to TextDataFile.jpr by clicking the Browse button to the right of the File field and entering TextDataFile.jpr in the File Name field. Click Save to exit this dialog.
  4. Optionally, enter information for a title (TextDataFile tutorial), your name, your company, and a project description (This tutorial...).
  5. Click Finish.
The AppBrowser window displays the project's structure:

Now that the basic project structure is created, let's start the Application Wizard to create a new Java application shell which contains a Frame.

  1. Select the File|New menu option, then double-click the Application icon. The first page of the Application Wizard appears.
  2. Leave the default package name as is.
  3. Enter TextDataFileApp in the Class field of the Application Class box.
  4. Click the Next button.
  5. Enter TextDataFileFrame in the Class field of the Frame Class box.
  6. Enter TextDataFile Tutorial in the Title field of the Frame Style box.
  7. Place a check beside the Generate Status Bar and and Center Frame On Screen options. Leave the remaining options (menu bar, tool bar, and generate about box) at their default values; they are not needed for this example.
  8. Click Finish.
In the Navigation pane (top left pane) of the AppBrowser, the TextDataFileApp.java and TextDataFileFrame.java files are added to the project.

Adding UI components to your application

The JBuilder UI Designer is used to build the user interface portion of this application. This step adds two UI elements to the application: a GridControl and a NavigatorControl. The GridControl is used to display two-dimensional data, in a format similar to a spreadsheet. The NavigatorControl is a set of buttons that help you navigate through the data displayed in a control such as a GridControl.

Displaying the UI design tools

To display the UI design tools that are used in this example:
  1. Select the TextDataFileFrame.java entry in the Navigation pane of the AppBrowser.
  2. Click the Design tab at the bottom of the Content pane (the large pane to the right).
The UI Designer displays in the Content pane (the large pane on the right side of the AppBrowser), the Component tree displays in the Structure pane (smaller pane on the bottom left), and the Inspector displays in a separate window to the right.

The Navigation pane allows you to easily and quickly select a file. Based on your selection, the other panes of the AppBrowser update as appropriate. The Component tree, for example, updates to display the elements in the selected file. Use the Component tree to navigate through these elements. The Source/Design panes also update to display the contents of the selected item.

Adding a UI component

  1. Open the UI Designer by clicking on the Design tab.
  2. Click the JBCL tab of the Component palette to see the various controls.
  3. Click the GridControl component: .
  4. Click where you want the upper left corner of the GridControl to start in the UI Designer window and hold the mouse button while you draw the GridControl to the desired size, ending at the lower right corner. The rectangular area displayed in the UI Designer is the default size of your application UI. You'll notice a larger rectangular area with a long thin rectangle beneath it. To keep this tutorial simple, draw your GridControl within the bounds of the larger shaded area. The long thin rectangle is the status bar created by the Application Wizard.

Your UI Designer window should look similar to this:

Tip:
To resize a UI component, click the mouse on the component to select it. When a component is selected, a border for the component becomes visible with small squares on the edges of the borders -- these are the component's "handles". Move the mouse over any handle; when the cursor changes to a double arrow, click the mouse and drag to resize the component.
Tip:
To change the alignment of a UI component, right-click on the component to bring up the context menu. You can choose to right, center, or left align the component within the UI Design window. You can also choose to top, middle, or bottom align the component within the UI Design window.

Notice that the Component tree in the lower left pane of the AppBrowser has a new entry: gridControl1. This is the GridControl you just placed in your application. JBuilder creates the corresponding source code immediately for the elements you've added to or modified in your application. To see this code, click the Source tab.

  1. The TextDataFileFrame.java entry should already be highlighted in the Navigation pane (upper left pane of the AppBrowser); if not, select it by clicking it. You'll see the following code that creates the instance of the gridControl1 object:
    GridControl gridControl1 = new GridControl();

  2. Click the jbInit() method in the Structure pane; you'll see the following code, which adds the GridControl to the application:
    bevelPanel1.add(gridControl1, new XYConstraints(4, 59, 385, 252));

    The numbers you see in the XYConstraints() method will likely differ as these are the size coordinates for the GridControl displayed above. Your coordinates will correspond to the size of the component you draw.

Switch back to the Design window (click the Design tab) and add a NavigatorControl just above the GridControl, following the steps used to add the GridControl. The NavigatorControl is located on the JBCL tab of the Component palette, and looks like this: .

Your application should look similar to this:

You've just finished creating the UI for your application. Before continuing, select the File|Save All menu option to save your work. The next step is to add DataExpress components and hook them up to the controls that were just created.

For more information on the fine points of UI design, see Designing a user interface.

Adding DataExpress components to your application

With DataExpress components, you have the choice of dropping them on the UI Designer as with visual controls, or you can drop them directly on the Component tree. The only indication that the DataExpress component is added is the reference to an instance of that object which appears in the Tree (and of course the source code generated in the Content pane); DataExpress components have no visual representation in the UI.

This application requires two DataExpress components:

These components are found on the Data Express tab of the Component palette. To add the TableDataSet DataExpress component to your application,
  1. Click the Data Express tab.
  2. Click the button to select the TableDataSet component.
  3. Click in the application design window or in the Component tree to add this component to your application. An entry for an instance of a TableDataSet object appears in the DataExpress folder of the Component tree as tableDataSet1.
Now add the TextDataFile component to your application following the steps above. The button for the TextDataFile is and once added, appears in the Component tree as textDataFile1.

All the components have been added to the application. Before continuing, select the File|Save All menu option to save your work. The next step is to connect them together by setting their properties.

Setting properties to connect the components

Now all the pieces needed for the application are in place, but they're distinct pieces that don't yet "talk" to each other. Setting the appropriate component properties will connect the pieces. Properties are set from the Properties tab of the Inspector. The Inspector window displays the properties for the component selected in the UI Designer window (for UI components) or the Component tree (for both UI and DataExpress components).

Setting properties of DataExpress components

The first step is to get the two DataExpress components "talking" to each other. This is accomplished by setting the fileName property of the TextDataFile component. This tells JBuilder where to find the text file that contains the data to be read into textDataFile1. Since TextDataFile is a DataExpress component, select it from the Component tree rather than the UI Designer window.

To set the fileName property of the TextDataFile component,

  1. Click the textDataFile1 object in the Component tree. The Inspector displays the properties for this component.
    Note: Make sure the Properties page is selected in the Inspector, not the Events page.
  2. Double-click the edit area next to the fileName property in the Inspector. It changes color to show that it is active for editing.
  3. Click the ellipsis button to display the File Name dialog.
  4. Click the Browse button to display the Open dialog. Click the parent directory icon to select the path of samples\borland\samples\tutorial\dataset\TextDataFile. Select the employee.txt file. Click the Open button to close the dialog.
  5. Click the OK button to close the File Name dialog. The resulting source code in the Source pane that sets this property is:
    textDataFile1.setFileName("c:\\JBuilder\\samples\\borland\\samples\\
       tutorial\\dataset\\TextDataFile\employee.txt"); 
    
    Use Alt+Z to toggle the Source window larger and smaller. If you installed JBuilder in a directory other than the one listed above, change the code to reflect the location of the sample files on your computer.
Note: Do not use a different text file than employee.txt at this time. Later examples (see "Importing data from a text file") show you how to work with your own data files.

Next, let's connect tableDataSet1 to the textDataFile1 component.

  1. Select tableDataSet1 in the Component tree. The Inspector displays the properties for this component.
  2. Double-click the area beside the dataFile property. Click the down arrow and select the entry for textDataFile1. This generates the following source code: tableDataSet1.setDataFile(textDataFile1);
  3. Save your work using the File|Save All menu option.

The employee.txt file works with the default settings stored in the TextDataFile component for properties such as delimiter, separator, and locale. If it required anything other than default values, the appropriate properties could be set at this point.

Now that the DataExpress components are connected to each other, the UI components can be connected.

Setting properties of UI components

The next step is to work with the two UI components, GridControl and NavigatorControl, as well as the StatusBar control that the wizard added for us. To work with these components, select them in either the UI Designer or the Component tree. You can tell when a UI component is selected in the UI Designer by the presence of borders and handles around the component.

To set the dataSet property of the GridControl component and connect the UI control to live data,

  1. In the UI Designer, select the GridControl component.
  2. Double-click the edit area beside the dataSet property in the Inspector.
  3. Click the down arrow that appears.
  4. Select tableDataSet1 from the drop-down list. This list contains all instantiated DataSet components (of which there is only one in this example).
Setting this property fills the GridControl with data from the text file. You should see live data in the UI Designer.

Also, set the dataSet properties of both the navigator and the status bar to tableDataSet1, following the steps as above. Then save your work.

When you set the dataSet property of the navigator, the two right-most buttons become dimmed and unavailable, because those buttons do not apply to DataSet objects whose data source is not a SQL server database.

When you set the dataSet property of the status bar, it displays the current row position and the row count. You cannot navigate the data in the UI Designer; but when you run the application, the status will update as you move the cursor through the data in the grid.

Your application should look like this:

Compiling, running, and debugging a program

Although you are in the UI Designer and have not run the program yet, data appears in the GridControl and your application looks complete. But your users won't be using your application in the JBuilder UI Designer. So, the next step is to compile, run, test, and possibly debug the application.

If you need to do so, review the chapters covering compiling and debugging as they discuss the two topics in much greater depth. To compile and run the application, click the Run button .

Note: If you click the Run button when your program has not been compiled, JBuilder automatically compiles your source and, if no compile errors are generated, runs your application.

If there are syntax errors, the program is not automatically run. If syntax errors are found, an Error pane containing error messages appears in the lower right of the AppBrowser window. Compiler or syntax errors tend to be easier to correct than logic errors. Logic errors are most noticeable at run-time when the application doesn't quite do what you'd like it to.

In this simple application, all properties were selected from drop-down lists or browsers, so syntax errors shouldn't be encountered. Had there been a need for manual typing, for example, a directory path and file name or custom code, chances would be greater for a syntax error to occur.

If all goes well, a message indicating a successful compile appears in the message line at the bottom of the Main window, and your application's UI should appear.

In the running application, you'll notice the following behavior:

Storing data locally

By default, all data sets store row data in memory (MemoryStore). To store data in a single file with a hierarchical directory structure, use a DataStore instead. Storing data in a DataStore provides persistent storage and caching for JBuilder DataSets, Java Objects, and arbitrary files. The advantages to using DataStore are that the implementation is pure Java, portable, there is a smaller footprint, and provides for better performance.

Summary

This program reads data from a text file, displays the data in a GridControl for viewing and editing, displays status messages to a StatusBar, and includes a NavigatorControl component to help browse though the data quickly.

After completing this application, you may want to explore other examples where more complex tasks are explored, showing how JBuilder presents warnings and errors, and working with additional UI and DataExpress components. See Common database application tasks for information on filtering data, locating data, and sorting data.