Tutorial: Querying a database

A QueryDataSet component is a JDBC-specific DataSet that manages a JDBC provider of data, as defined in the query property. Using a QueryDataSet component in JBuilder, you can extract data from a data source into a StorageDataSet component. This action is called "providing". Once the data is provided, you can view and work with the data locally in data-aware components. When you want to save the changes back to your database, you must resolve the data. The DataExpress architecture is discussed in more detail in "Understanding JBuilder database applications".

QueryDataSet components enable you to use SQL statements to access, or provide, data from your database. You can add a QueryDataSet component directly to your application, or add it to a data module to centralize data access and control business logic.

Tutorial: Querying a database using the JBuilder UI

The following tutorial shows how to retrieve data using a QueryDataSet component. This example also demonstrates how to attach the resulting data set to a JdbTable for data viewing and editing.

Retrieving data by querying a database

To create the application and retrieve data from a table,

  1. Select File|Close All.
  2. Select File|New. Double-click the Application icon and accept all defaults to create a new application.

  3. Make sure the JDataStore library is included in the project. To do this,
    1. Select Project|Default Project Properties.
    2. Select the Required Libraries tab.
    3. Select Add.
    4. Select JDataStore. Click OK twice to close the dialog.

  4. Select the Design tab to activate the UI designer.

  5. Click the Database component on the Data Express tab of the component palette, then click anywhere in the Design pane to add the component to the application.

    Open the connection property editor for the Database component by double-clicking the connection property ellipsis in the Inspector. Set the connection properties to the JDataStore sample EMPLOYEE table, as follows:
    Property name Value
    Driver com.borland.datastore.jdbc.DataStoreDriver
    URL jdbc:borland:dslocal:/usr/local/jbuilder/samples/JDataStore/datastores/employee.jds (the employee.jds database is located under the samples directory of your JBuilder installation directory, which may be different on your system. You can browse to this file to reduce the chance of making a typing error, click the Browse button)
    Username Enter your name
    Password none allowed

  6. Add a QueryDataSet component to the designer by clicking on the QueryDataSet component on the Data Express tab and then clicking anywhere in the Design pane. Select the query property of the QueryDataSet component in the Inspector and set the following properties:
    Property name Value
    Database database1
    SQL Statement select * from employee

    Click Test Query to ensure that the query is runnable. When the area beneath the button indicates Success, click OK to close the dialog.

  7. Select a DBDisposeMonitor component from the "more dbSwing" tab. Click in the Structure pane to add it to the application. The DBDisposeMonitor will close the JDataStore when the window is closed.

  8. Set the DBDisposeMonitor's dataAwareComponentContainer property to this.

Creating the UI

This topic shows how to create a UI for your application using dbSwing components to view and navigate data in your application. To create the UI,

  1. Select a JdbNavToolBar component from the dbSwing tab. Drop the component in the area slightly above the panel in the Design frame. JdbNavToolBar automatically attaches itself to whichever DataSet has focus.

    This will enable you to move quickly through the data set when the application is running, as well as provide a default mechanism for saving changes back to your data source.

  2. 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.

  3. Add a TableScrollPane component from the dbSwing tab to the designer.

    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.

  4. Drop a JdbTable component from the dbSwing tab into the TableScrollPane component. Set its dataSet property to queryDataSet1.

    You'll notice that the designer displays a table with live data.

  5. Select Run|Run Project to run the application and browse the data set.

In the running application, you can view and modify data, add or delete records. To save changes back to the data source, you can use the Save Changes button on the toolbar component or, for more control on how changes will be saved, create a custom data resolver, as described in the topic "Saving changes back to your data source".