Tutorial: Offline editing with JDataStore

This tutorial provides the steps for creating an application that uses a local DataStore component to enable offline editing of data from a remote database. Data from the remote database server is stored locally to allow editing of the data even when a connection to the server is not available. Once the connection becomes available, changes made locally can automatically be updated on the server.

To create this application:

  1. Start the remote JDataStore database server by selecting Tools | JDataStore server from the menu.
  2. Create a new application by selecting File|New from the menu and double-clicking the Application icon. Use the name OfflineEditingApp. Accept all defaults.
  3. Double-click on the frame file in the navigation pane to load it into the content pane. Then click the Design tab to start the Designer.
  4. Click a Database component on the Data Express tab of the Component palette. Click in the Component tree to add the Database component to the application.
  5. Open the connection property editor for the Database component in the Inspector. Set the connection properties to access the sample JDataStore employee.jds database (found below the samples/JDataStore/datastores subdirectory of your JBuilder installation directory) via the remote JDataStore JDBC driver:

    Field

    Value

    Driver

    com.borland.datastore.jdbc.DataStoreDriver

    Connection URL

    jdbc:borland:dsremote://localhost//usr/local/jbuilder/samples/JDataStore/datastores/employee.jds

    Username

    <enter your name>

    Password

    <not required>

    Click the Test Connection button to check that the connection properties have been correctly set. Results of the connection attempt are displayed in the area near the button. When the connection is successful, click OK.

  6. Add a DataStore component from the Data Express tab to the Component tree. Data retrieved from the remote database server will be stored locally in this DataStore component.

    Adding a DataStore component writes an import statement for the datastore package to your code, and adds the Datastore library to your project properties if it was not already listed.

  7. Open the fileName property editor for the DataStore component. Type the name for the local JDataStore file. Be sure to include the full path; use the Browse button to help. You do not have to specify a file extension; a JDataStore always has the extension .jds. Click OK.

    Note: The Designer will automatically create this JDataStore file for you (in a subsequent step of this tutorial) when a QueryDataSet component is used. Then when you run this application, the JDataStore file will already be there. But if you run this application on another computer, the JDataStore file won't already be there. You will have to add extra code to create the JDataStore file if necessary, as shown in "Creating a JDataStore file" and in the pre-built sample project for this tutorial.

  8. Add a QueryDataSet component to the Designer by clicking on the QueryDataSet component on the Data Express tab and then clicking in the Component tree.

    Open the query property editor for 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 near the button indicates Success, click OK to close the dialog box.

  9. Select the storeName property in the Inspector. Enter the name employeeData.
  10. Select the store property for the QueryDataSet. Select dataStore1 from the list.
  11. Drop a JdbNavToolBar component from the dbSwing tab of the component palette near the top of the main panel (contentPane) in the designer.
  12. Drop a TableScrollPane component from the dbSwing tab into the middle of the main panel. Then drop a JdbTable component from the dbSwing tab inside the TableScrollPane. Set its dataSet property to queryDataSet1.
  13. Drop a JdbStatusLabel component from the dbSwing tab to the bottom of the main panel.
  14. Click on the DBDisposeMonitor component of the More dbSwing tab and click anywhere in the designer tree to add it to your project. In the inspector, set the DBDisposeMonitor's dataAwareComponentContainer property to 'this' to have it automatically close your local and remote DataStores when you close the frame.
  15. Select File | Save all from the menu to save all your changes.
  16. Select Run | Run project from the menu to run the sample.

In the running application, make some changes to a row of the data and click the Post button on the toolbar to save the changes to the local JDataStore file. Changes are also saved to the file when you move off of a row, just as they are with an in-memory data set (MemoryStore).

Note: A data set in a JDataStore can have tens or hundreds of thousands of rows. Handling that much data using an in-memory data set would have an undesirable impact on application performance.

Close the application and run it again. You see the data as you edited it in the previous run. This, of course, is very different from the behavior of an in-memory data set. If you want, you can exit the application, shut down the JDataStore Server (select File | Shutdown from the server's main menu), and run the application again. Without any connection to the SQL database, you can continue to view and edit data kept in the local JDataStore. This would be especially useful if you want to work with data offline, such as at home or on an airplane.

Understanding how JDataStore manages offline data

So far in the tutorial, nothing has been saved back to the SQL database on the server. On the JdbNavToolBar,

Options set in the queryDescriptor also have an effect on how data is stored, saved, and refreshed. In the queryDescriptor in this example, the Execute Query Immediately When Opened option is selected. This option indicates how data is loaded into the local JDataStore file when the application was first run. On subsequent runs, the execution of the query is suppressed, because the data set is found in the local JDataStore file instead of on the server. As a result,

The Execute Query Immediately When Opened option is not allowed to overwrite existing data. This means that you can safely close and reopen a data set to change property settings in either a MemoryStore or in a JDataStore without losing editing changes.

Once you've got data in the JDataStore file, you can run this application and edit data whether the database server is available or not. When you are working offline, you have to remember not to click the toolbar's Save or Refresh button; you will get an exception because the attempt to connect will fail, but you won't lose any of the changes you have made.

The following steps show how to add a JToggleButton to the toolbar to explicitly control whether you are working offline or connected to the database server:

  1. In the Designer, click the JToggleButton component on the Swing tab of the component palette, and then click inside the JdbNavToolBar to add the button to the toolbar.
  2. Set the following properties on the JToggleButton in the Inspector:

    Property name

    Value

    text

    Connect

    preferredSize

    100, 30

  3. Click on the Events tab of the Inspector, and double-click in the area to the right of the itemStateChanged property to have the Designer automatically generate the appropriate event-handling code for you. Within the body of the method the Designer created for you, insert the following code to connect and disconnect from the remote database based on the state of the JToggleButton:
      void jToggleButton1_itemStateChanged(ItemEvent e) {    // code generated for you automatically by the designer
        try {
          if (jToggleButton1.isSelected()) {
            // Connect to SQL database
            database1.openConnection();
            jdbNavToolBar1.setButtonStateSave(JdbNavToolBar.ENABLED);
            jdbNavToolBar1.setButtonStateRefresh(JdbNavToolBar.ENABLED);
            jToggleButton1.setText("Disconnect");
          }
          else {
            // Disconnect from SQL database
            database1.closeConnection();
            jdbNavToolBar1.setButtonStateSave(JdbNavToolBar.DISABLED);
            jdbNavToolBar1.setButtonStateRefresh(JdbNavToolBar.DISABLED);
            jToggleButton1.setText("Connect");
          }
        }
        catch (Exception ex) {
          ex.printStackTrace();
        }
      }
    

  4. Select File | Save all from the menu to save all your changes.
  5. Select Run | Run project from the menu to run the sample.

You can now click on the toggle button to explicitly connect and disconnect from the server. When connected to the server, you can press the toolbar's Save and Refresh buttons to save changes back to and refresh data from, the remote database server. When working offline, those buttons are disabled on the toolbar to remind you that you need to reconnect in order to save your changes back to the server.