Tutorial: TextDataFile sample application

This introductory tutorial steps you through creating a basic database application and user interface (UI) using the JBuilder design tools to read data from a text file. You can create a database application even if you are not connected to a SQL or desktop database. You can create the database application using data in a text file (in this case, a data file that ships with JBuilder) and the DataExpress TextDataFile and TableDataSet components. This tutorial then explores the JBuilder DataExpress architecture and applies database concepts to the tutorial even though this application does not connect to a SQL database.

The UI for this application consists of three components: a table component that displays the data from the text file, a toolbar to aid in browsing through the data, and a status area that displays messages.


Creating the application structure

The first step when creating an application in JBuilder is to set up the framework for the application. JBuilder's visual design tools can be used to quickly create the application structure and, in future steps of this tutorial, to read data from the text file and to develop the user interface.

To create the application structure,

  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. Accept the default path. Change the project name by clicking the Browse button and entering TextDataFile.jpr in the File Name field. Click Save to exit this dialog box.
  4. Click Next.
  5. Optionally, enter information for a title (TextDataFile tutorial), your name, your company, and a project description (This tutorial...).
  6. Click Finish.

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, a new UI container.

  1. Select File|New from the menu. Double-click the Application icon. The first page of the Application wizard displays.
  2. Accept the defaults.
  3. Click Next.
  4. Enter TextDataFile Tutorial in the Title field.
  5. Click Finish.
The Application1.java and Frame1.java files are added to the project and are displayed in the project pane (top left pane).


Adding DataExpress components to your application

DataExpress components can be added to your application when the Design pane is selected. You add the components by selecting them from the DataExpress tab of the component palette and then dropping them either in the Design pane or directly into the Structure pane (lower left pane of the AppBrowser). When a DataExpress component is added to the application, an instance of that object appears in the Structure pane and its generated source code displays in the Source pane when it is selected. DataExpress components have no visual representation in the UI.

When importing data from a text file, as we are doing in this tutorial, two DataExpress components are needed:

To add the DataExpress components to your application,

  1. Select the Design tab at the bottom of the Content pane.
  2. Select the DataExpress tab from the component palette.
  3. Add a TextDataFile component to your application.

    To do this,

    1. Click the TextDataFile component to select it.
    2. Click in the structure pane to add it to the application.

    An entry for an instance of a TextDataFile object appears in the DataExpress folder of the structure pane as textDataFile1.

  4. Add a TableDataSet to the application.

    To do this,

    1. Click the TableDataSet component to select it.
    2. Click in the structure pane to add it to the application.

    An entry for an instance of a TableDataSet object appears in the DataExpress folder of the structure pane as tableDataSet1.

  5. Choose File|Save All to save your work.

Setting properties to connect the components

The next step is to connect the DataExpress components so that they can "talk" to each other. Setting the appropriate component properties connects the DataExpress components. Properties are set from the Properties tab of the Inspector. The Inspector displays the properties for the component selected in the UI designer (for UI components) or in the structure pane (for both UI and DataExpress components when the Design page is displayed). For more information on using the Inspector, see "Getting Started: Setting component properties in the Inspector" in the Programmer's Guide.

To get the two DataExpress components "talking" to each other, set 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 structure pane rather than from the UI designer.

To set the fileName property of the TextDataFile component,

  1. Select the textDataFile1 object in the Structure pane. The Inspector displays the properties for this component. Note: Make sure the Properties page is selected in the Inspector, not the Events page.
  2. Select 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 box.
  4. Click the Browse button to display the Open dialog box. Browse to your JBuilder installation directory, and select samples/DataExpress/TextDataFile/employee.txt. Click Open.
  5. Click OK to close the File Name dialog box.
  6. Click the Source tab to view the resulting source code, which should look similar to:
    textDataFile1.setFileName("/usr/local/jbuilder/samples/com/borland/samples/DataExpress/TextDataFile/employee.txt"); 
    

    The sample files are installed beneath the samples subdirectory of your JBuilder installation directory. For example, /usr/local/jbuilder/samples/DataExpress/. You may need to browse to find the appropriate samples directory on your computer.

Note: This tutorial will not work if you use a different text file than employee.txt at this time. This project also contains a SCHEMA file needed to import this text file. Later examples show you how to work with your own data files. See "Importing data from a text file."

The next step is to connect tableDataSet1 to the textDataFile1 component.

  1. Select the Design tab.
  2. Select tableDataSet1 in the structure pane. The Inspector displays the properties for this component.
  3. Click the area beside the dataFile property. Click the down arrow and select the entry for textDataFile1.
  4. Select the Source tab to see the generated source code:

    tableDataSet1.setDataFile(textDataFile1);
    

  5. Choose File|Save All to save your work.

The employee.txt file is designed to work with the default settings stored in the TextDataFile component for properties such as delimiter, separator, and locale. If it was designed differently, the appropriate properties could be set at this point.


Creating a user interface

The JBuilder UI designer is used to build the user interface for this application. The following steps add UI elements to the application: a JdbTable (and its surrounding TableScrollPane), a JdbNavToolBar, and a JdbStatusLabel. The JdbTable is used to display two-dimensional data, in a format similar to a spreadsheet. The JdbNavToolBar is a set of buttons that help you navigate through the data displayed in a JdbTable. The JdbStatusLabel displays the current record and any error messages.

Adding a UI component

The first step in setting up a user interface is to determine the appropriate layout for your application. To learn more about layouts, see "Using layout managers" in the Programmer's Guide.

If you want to change the layout,

  1. Click the Design tab at the bottom of the content pane.
  2. Select contentPane(BorderLayout) in the Structure pane.
  3. Select layout in the Inspector. Click the down arrow for the layout property. Choose the appropriate layout. The default is fine for this example.

To add UI components to your application,

  1. Click the dbSwing tab of the component palette to see the various components.

  2. Click on the JdbNavToolBar component on the dbSwing tab of the component palette. Drop the component in the area slightly above the panel in the Design pane. JdbNavToolBar automatically attaches itself to whichever StorageDataSet has focus.

    The JdbNavToolBar component enables you to move quickly through the data set when the application is running.

  3. Click on the JdbStatusLabel component on the dbSwing tab of the component palette. Drop the component in the area slightly below the panel in the Design pane. JdbStatusLabel automatically attaches itself to whichever DataSet has focus.

    Among other information, the status bar displays information about the current record or current operation.

  4. Click on the TableScrollPane component on the dbSwing tab. Drop the component in the center of the Design pane.

    Scrolling behavior is not available by default in any Swing component or dbSwing extension, so, to get scrolling behavior, we add the scrollable Swing or dbSwing components to a JScrollPane or a TableScrollPane. TableScrollPane provides special capabilities to JdbTable over JScrollPane. See the dbSwing documentation for more information.

  5. Click on the JdbTable component on the dbSwing tab. Click inside the TableScrollPane component in the Design pane to add the JdbTable to the TableScrollPane container.

The Structure pane in the lower left pane of the AppBrowser now has an entry for the JdbTable, jdbTable1. JBuilder creates the corresponding source code immediately for the elements you've added or modified in your application. To see this code, click the Source tab.

The next step is to connect the DataExpress components to the UI components. For more information on the fine points of UI design, see "Designing a user interface" in Building Applications with JBuilder.

To connect the DataExpress components with the JdbTable, you must specify a DataSet in the dataSet property of the component.

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

  1. Click the Design tab.
  2. Select jdbTable1 in the Structure pane.
  3. Click the edit area beside the dataSet property in the Inspector.
  4. Click the down arrow that appears.
  5. Select tableDataSet1 from the drop-down list. This list contains all instantiated DataSet components (of which there is only one in this example).

The column headers and live data appear in the table in the Design pane.


Compiling, running, and debugging your application

In the UI designer, data appears in the JdbTable and the application looks complete. But users will not be running your application in the JBuilder UI designer. So, the next step is to compile, run, test, and possibly debug the application.

To compile and run the application, click the Run Project button.

Clicking the Run button compiles your source code (if it has not already been compiled), and, if no errors are found, a message indicating that the source code has successfully compiled displays in the message box at the bottom of the AppBrowser, and the application UI displays in a separate window.

If there are syntax errors in the source code, 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. Double-click on the error message to locate the source of the error in the code. Errors in programming logic may not appear until run time when the application performs in unexpected ways.

In this simple application, you will probably not encounter any syntax errors because all properties were selected from drop-down lists or browsers. Syntax errors are most likely to occur when you modify the generated code, or when you add in Java code manually.

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

Summary

The application created for this tutorial reads data from a text file, displays the data in a JdbTable for viewing and editing, displays status messages to a JdbStatusLabel, and includes a JdbNavToolBar component to help browse though the data.

This tutorial was intended to familiarize you with the JBuilder environment and the basic requirements for developing a database application with JBuilder.