Using the JDataStore Explorer

JDataStore is a feature of JBuilder Professional and Enterprise, and the Inprise Application Server.

Using the all-Java JDataStore Explorer, you can:


Launching the JDataStore Explorer

There are three ways to launch the JDataStore Explorer:

Figure 6.1   JDataStore Explorer after launch

Starting the JDataStore Explorer from the command line

JDataStore Explorer requires the following JARs:

These files are also required if you want the online help to be available:

An executable file for the JDataStore Explorer is provided, and it can be started from the command line. The executable uses the classpath and main class name settings in the dse.config file.

The main class for the JDataStore Explorer is com.borland.dbtools.dsx.DataStoreExplorer. The command line for starting the server with default options (after setting the classpath) is:

java com.borland.dbtools.dsx.DataStoreExplorer 

You can also specify the options listed in the following table:

Table 6.1   JDataStore Explorer startup options 

Option

Description

-ui=<uiType>

The look and feel of the UI. One of the following:

  • windows
  • motif
  • metal
  • none
  • <LookAndFeel class name>

-h=<helpDir>

The directory that contains online help files

<.jds filename>

A JDataStore file to open on startup

-?

Displays a message listing these options


Basic JDataStore operations

Most JDataStore operations in the JDataStore Explorer require a JDataStore file. You can create a new one or open an existing JDataStore file. You can have more than one JDataStore file opened at the same time.

Creating a new JDataStore file

To create a new JDataStore file,
  1. Select File|New or click the New JDataStore toolbar button. This opens the New JDataStore dialog box:

    Figure 6.2   New JDataStore dialog box

  2. Enter a name for the new JDataStore file.
  3. (Optional) Choose a block size other than the default 4KB.

  4. Make sure the Install TxManager check box is set properly:

  5. Click OK. The store is created and opened in the JDataStore Explorer.

Opening an existing JDataStore file

To open an existing JDataStore file,

  1. Select File|Open or click the Open JDataStore toolbar button. This opens the Java version of the standard File Open dialog box.
  2. Choose the file to open and click Open.

The JDataStore Explorer keeps track of the five most recently opened files. You can open them directly from its File menu.

Setting options for opening JDataStore files

You might want to open a JDataStore file in read-only mode to temporarily bypass transaction support or to attempt to open a file that has been damaged. Select View|Options to open the Options dialog box.

Figure 6.3   JDataStore options dialog box

Opening a JDataStore file that was not closed properly

If the JDataStore file is already marked as open, which happens if the JDataStore file was not closed properly, a dialog box appears asking if you want to try and open the JDataStore anyway.

Figure 6.4   JDataStore marked open dialog box

If this occurs, follow these steps:

  1. Verify that there is no process that might still have the JDataStore file open (in particular, check the Task Manager for any rogue javaw processes):
  2. Attempting to reopen the file might take several seconds. If the JDataStore file was not closed properly, another dialog box informs you of this condition. Click OK to attempt to recover the JDataStore file.

  3. After you successfully open a JDataStore file that was left marked as open, a dialog box appears that gives you the opportunity to verify the contents of the JDataStore file. Click Yes to verify the JDataStore contents or No to skip the verification.

Viewing JDataStore file information

When a JDataStore file opens, its directory appears in a tree control on the left. Each open JDataStore file is a node directly off the root node. Information about the JDataStore file appears in the viewer area on the right.

Figure 6.5   JDataStore Explorer displaying JDataStore file information

This information includes:

You can view this information at any time by selecting the node in the tree that contains the JDataStore file name.

Viewing stream contents

The JDataStore directory appears in the tree control on the left. The directory uses forward slashes ("/") in the stream names to synthesize a hierarchical structure. In addition, known stream types such as tables and text files appear under a corresponding node in the tree. You can use the View|Expand All and View|Collapse All menu items to help manage the directory tree.

When you select a stream in the tree, the stream contents display if there is an appropriate viewer. There is a built-in viewer for table streams.

Figure 6.6   JDataStore Explorer displaying table stored in JDataStore

The figure shows a JDataStore file with an "Employees" table in the root directory. The View page displays the contents of the table with navigation controls. You can search, edit, add, and delete data. The Info tab displays information on the columns in the table.

File streams are handled by their file-name extension. JDataStore Explorer ships with viewers for the following file types:

For example, here is the text file "demo/explor.txt":

Figure 6.7   JDataStore Explorer displaying text file stored in JDataStore

This is the image file "demo/duke.gif":

Figure 6.8   JDataStore Explorer displaying image stored in JDataStore

Renaming streams

Use this operation to rename a stream or to move a stream to another directory:
  1. Select the stream to rename/move in the directory tree. (You can't rename deleted streams. You must undelete them first.)

  2. Select Edit|Rename.

  3. Type a new name in the Rename dialog box. You can't use the name of another existing active stream.

  4. Click OK.

Deleting streams

When you delete a stream, the blocks it used are marked as available. It's possible to undelete a stream, although some of the blocks might have been reclaimed by other streams. See "How JDataStore reuses deleted blocks" for more details.

To delete a stream,

  1. Select the stream to delete in the directory tree.

  2. Select Edit|Delete. The stream is marked as deleted in the tree.

Undeleting streams

If a deleted stream is visible in the directory tree, you can undelete it. You can't undelete a stream if there is another active stream with the same name in the same directory, because you can't have two streams with the same name.

Undeleting a stream doesn't guarantee all the data in the stream will be recovered. See "How JDataStore reuses deleted blocks" for more details.

To undelete a stream,

  1. Select the deleted stream to undelete in the directory tree.
  2. Select Edit|Undelete. The deleted mark is removed from the stream icon.

Copying JDataStore streams

You can use the JDataStore Explorer to copy streams to another JDataStore file, much like the DataStoreConnection.copyStreams() method. While you can't use this option to make copies of streams within the same JDataStore file, the JDataStore Explorer automatically creates a new JDataStore file for you.

To copy streams,

  1. Select Tools|Copy JDataStore. This opens the Copy Streams dialog box:

    Figure 6.9   Copy Streams dialog box

  2. Specify the various Copy Streams options, as summarized in the following table. (For more information, see "copyStreams parameters.")

    Table 6.2   Copy Streams options 

    Name

    Description

    Destination JDataStore

    The name of the JDataStore file to copy to.

    Destination directory

    Names of copies of streams have their Source directory replaced with this. The destination directory should be the same as Source directory if the name should not be changed.

    Source directory

    Stream name must begin with this to be pattern-matched. An empty string pattern-matches all streams.

    Source Pattern

    Stream name pattern to match, with standard * and ? wildcard characters.

  3. Click OK.

Verifying the JDataStore

To verify the structure and contents of the JDataStore, select Tools| Verify JDataStore or click the Verify JDataStore toolbar button.

The JDataStore Explorer verifies the entire store and displays the results in the Verifier Log window. After you've closed the log window, you can view it again by selecting View|Verifier Log.

Making the JDataStore transactional

You can make a non-transactional JDataStore transactional with the JDataStore Explorer:
  1. Select TxManager|Install. (If the JDataStore is already transactional, that menu option will be disabled.) This opens the TxManager Properties dialog box:

    Figure 6.10   TxManager Properties dialog box

  2. The dialog box contains default settings for the TxManager object:

  3. Click OK.

Modifying transaction settings

To modify transaction settings for a JDataStore,
  1. Select TxManager|Modify. (If the JDataStore is not transactional, that menu option will be disabled.) This opens the TxManager Properties dialog box.

  2. Change settings as desired.

  3. Click OK.

Removing transaction support

You can check if a JDataStore is transactional by examining the TxManager menu. If the Enabled menu option is checked, the JDataStore is transactional. If the menu option is disabled, the JDataStore is not transactional.

To make a transactional JDataStore non-transactional, uncheck TxManager|Enabled. This immediately removes transaction support.

Closing JDataStore files

When you are done with the JDataStore file, you should close it to ensure that all changes are written properly. You don't need to close open JDataStore files before exiting the JDataStore Explorer. The files close automatically.

To close the current JDataStore file, select File|Close. To close all open JDataStore files, select File|Close All.


JDataStore Explorer as a query console

When the JDataStore is used as a persistent data cache (which means that the data isn't lost when the application is shut down), it's the application's job to contain the logic to manipulate the data. This logic can include code to connect to a server, SQL statements to load data from the server into datasets, and code to save updates back to the server, in addition to whatever presentation and manipulation of the data the application allows.

The JDataStore Explorer can take the place of a simple application. Within the Explorer, you can define a connection to a database, define SQL queries against tables in that database, run the queries to produce datasets that are saved in the JDataStore, edit the datasets, save your changes back to the database, and rerun queries to get the latest server data--all without writing code.

You can use this mechanism to simply import data from another database into a JDataStore. Because the query and connection information used to import the data is saved, you can easily reimport the data if you want.

Using JDataStore Explorer to manage queries

This discussion of ways to store and execute queries might bring to mind the distinction between queries that run against a server to produce store datasets and queries against store tables that produce new tables (which might or might not be saved in a JDataStore). In the former case, the JDataStore provides persistent storage for tables produced by querying a server. In the latter case, the JDataStore itself functions as a server and, like other servers, is accessed by running SQL queries through a JDBC connection.

Here we introduce a third, complementary use of the JDataStore: as a place to store connection information and queries. These queries can be of either type just mentioned; they can get their data either from server tables or from datasets in a JDataStore. In either case, the result of running a query through the JDataStore Explorer is always another store table.

When you use the Explorer to manage queries, it's important to understand the objects involved and how they are related:

This is the hierarchy:

The user interface for saving changes and refreshing data reflects this organization, as described in "Saving changes and refreshing data."

The connection information and query SQL statements, which are usually embedded in your application code, are saved in the JDataStore in two special tables named "SYS/Connections" and "SYS/Queries."

JDataStore Explorer limitations

Remember that although the JDataStore Explorer can execute queries and save changes to the dataset back to server tables, it has no application-specific logic. The data is presented in just a simple tabular display. Data entry support and data validation that is usually provided by code in a data module won't be performed. If you edit data in the Explorer, you won't see any edit masks or pick lists, you won't be prevented from entering values that violate minimum or maximum constraints, and you might be able to leave required fields empty or violate referential integrity constraints. (Constraints defined in the server are enforced, but not until you attempt to save your changes.) The Explorer is useful for working with test data or making small, careful changes to production data, but it's not a substitute for a data module written with the specific integrity requirements of its datasets in mind.

Creating and maintaining queries and connections

To use the JDataStore Explorer to manage queries or to import a table from another database, you must have an open JDataStore. Then, to define a query, select Tools|Import|Tables. The Import Tables dialog box opens:

Figure 6.11   First page of Import Tables dialog box

The first time you define a query, there won't be any connections to associate it with. The New button next to the Connection field lets you define a new connection through the New JDBC Connection dialog box.

Figure 6.12   New JDBC Connection dialog box

Enter the same parameters as you would in the Connection property editor for a database: JDBC Driver Name, URL, Username, and Password. You can also specify extended properties for the connection. When defining queries later, you can choose an existing connection or define a new one.

Once you have a connection to a database, you'll see a list of available tables. After selecting the desired tables, you can click Finish to simply import those tables. If you want more control over what is imported, click Next to go to the next page.

Figure 6.13   Second page of Import Tables dialog box

This page lists all the tables that will be imported:

Click Finish to import the data and store the queries.

The first time you open the Import Tables dialog box, two empty table streams named "SYS/Connections" and "SYS/Queries" are created. Queries that you create go into "SYS/Queries," and connections you create go into "SYS/Connections." When you finish defining the first query by clicking OK, each table will have one row.

To maintain connections or queries, select the "Connections" or "Queries" table under the "SYS/DataStore Queries" branch in the Explorer tree. You can

Fetching and editing data

Right after saving a new query, the JDataStore Explorer attempts to execute that query to fetch its data. You'll see the tree pane of the Explorer update to show the newly imported table using the store name you specified. After that, you can re-execute the query to refresh the data manually. Note that refreshing data discards any unsaved changes.

To execute a query, select it in the "SYS/Queries" table, click Refresh Table, and respond "Yes" to the warning about unsaved changes.

View a table by selecting it in the Explorer's tree. On the right side of the Explorer, you see the table in a grid. Choose the Info page to see the dataset's column names and their data types. You can edit the table on the View page, but be sure you understand the risk to data integrity first.

After editing, you can save your changes or discard them. You discard changes by refreshing the dataset and responding "Yes" to the warning about unsaved changes.

Saving changes and refreshing data

You can save changes and refresh data on three different levels:

To refresh or save changes from a single table, select the row in "SYS/Queries" for the query that creates that table. Buttons labeled Refresh Table and Save Table Changes are available, indicating that only the table provided by that query will be affected.

To refresh or save changes from all the tables for a connection to a database, select that connection's row in the "SYS/Connections" dataset. Buttons labeled Refresh Connection Queries and Save Connection Changes are available, indicating that all tables produced by querying that connection's database will be affected.

To refresh or save changes from all the datasets for which you've defined queries through the JDataStore Explorer, select Tools|Refresh JDataStore or Tools|Save JDataStore Changes. These commands re-execute every query or save changes for every dataset with an associated query for those queries that have their Enable Refresh on Tools Menu and Enable Save on Tools Menu options enabled. You can change these settings for each query in the "SYS/Queries" table.

Figure 6.14   Entries in the SYS/Queries table


Importing tables and files

In addition to importing tables from other databases, the JDataStore Explorer makes it easy to import delimited text files as table streams and arbitrary files as file streams.

Importing text files as tables

The contents of the text file must be in the delimited format that DataExpress exports to, and there must be a SCHEMA file with the same name in the directory to define the structure of the target dataset.

SCHEMA files (which end with a .schema file-name extension) are created when you export a dataset to a text file through the com.borland.dx.TextDataFile.save() method. It's recommended that you export data from your dataset to generate the SCHEMA file. To give you an idea of what one looks like, here is one for a simple three-column dataset:

[]
FILETYPE = VARYING
FILEFORMAT = Encoded
ENCODING = Cp1252
DELIMITER = "
SEPARATOR = 0x9
FIELD0 = ID,Variant.INT,-1,-1,
FIELD1 = Name,Variant.STRING,-1,-1,
FIELD2 = Update,Variant.TIMESTAMP,-1,-1,

This SCHEMA file defines the double quote as the string delimiter and the tab character as the field separator. There are three columns, an integer, a string, and a timestamp.

Once you have a SCHEMA file to accompany the text file, follow these steps to import the text file as a table,

  1. Select Tools|Import|Text Into Table. This opens the Import Delimited Text File dialog box.

  2. Supply the input text file and the store name of the dataset to be created. Because this operation creates a dataset, not a file stream, you'll probably want to omit the extension from the store name.

  3. Click OK.

Importing files

To import a file as a file stream,

  1. Select Tools|Import|File.
  2. Supply an input file name and the store name of the file stream to be created.

  3. Click OK.


Creating tables

You can use the JDataStore Explorer to visually create new tables for a JDataStore database. To create a table:
  1. Open the JDataStore Explorer. (If you are in JBuilder, choose Tools|JDataStore Explorer.)
  2. Choose File|Open in the JDataStore Explorer and select the database for which you want to create a new table.
  3. Choose Tools|Create Table in the JDataStore Explorer to open the Create Table dialog box.

    createtables1_dsex.gif

  4. Type a name for the new table in the Table Name field.

  5. Select a locale if you are internationalizing the table. Otherwise, leave the value <null>.
  6. Click the Insert New Row button  insertnew.gif on the Navigation bar to create a new row.
  7. Click in the Column Name field and type the name of the new column.
  8. Click in each of the column property fields on that row you want to define, and select or enter a value. For each column, you must specify at least a column name and data type. You may also specify other properties as needed. (See the Column class for a description of the meaning of the Column properties.)
  9. Continue creating the rest of the columns in this manner, rearranging their order in the table as desired. Use the Navigation bar buttons to add or insert additional rows, move to different rows, and rearrange the rows you have added.
  10. Click OK when you are finished creating and defining all the columns.

It is also possible to modify an existing table's structure in the JDataStore Explorer. Select a table in the tree on the left, and click the Structure tab. The UI for the Structure tab is the same as the Create Table dialog box.

For more information on using the Create Table dialog box, click the Help button on the dialog box.


Creating indexes

You can use the JDataStore Explorer to visually create an index for a JDataStore table. To create an index:

  1. Open the JDataStore Explorer. (If you are in JBuilder, choose Tools|DataStore Explorer.)
  2. Choose File|Open in the JDataStore Explorer and select a database.
  3. Choose Tools|Create Index in the JDataStore Explorer to open the Create Index dialog box.

    createindex.gif

  4. Choose the name of the table for which you want to create an index in the Table Name drop-down list.

  5. Type the name for the index in the Index Name field.
  6. Specify a Locale object to use for determining how to do the sort if needed. Otherwise, leave the value <null>.
  7. Check Unique if you want the combined results of the selected columns to be unique for every row.
  8. Check Case Insensitive if you don't want the sort to match items by case.
  9. Check Sort as Inserted if you want new rows to remain where they were inserted.
  10. Select which columns to include in the sort. Use the arrow buttons to move columns from the Available list to the Selected list and back.
  11. Specify the sort order as Ascending or Descending for each column in the Selected list.
  12. Click OK when you are finished specifying the index criteria. The index is added to the list of indexes for that table in the tree at the left of the JDataStore Explorer.

Two tabs are now present in the right half of the JDataStore Explorer: View and Info.

For more information on using the Create Index dialog box, click the Help button on the dialog box.


Executing SQL

You can execute arbitrary SQL statements with the currently selected JDataStore file as the database. If the JDataStore file is not transactional, you can only do read-only queries. If a non-transactional JDataStore is not already open in read-only mode, it will automatically be closed and reopened in read-only mode. To execute SQL, select Tools|SQL or click the SQL toolbar button, which opens the SQL dialog box:

Figure 6.15   SQL dialog box

You can type in SQL statements directly or execute files containing SQL. Statements that you type are recorded and you can scroll through them with the Previous and Next buttons to modify and re-execute recorded statements. Result sets returned by SQL statements are displayed in the lower half of the dialog box.


JDataStore file operations

The JDataStore Explorer also provides a few functions that do not have a direct analogue in the JDataStore API.

Packing the JDataStore file

Packing the JDataStore file renames the existing file (by prepending "BackupX_of_" where X is an auto-incrementing number), and it copies all the streams from the old file to the new copy of the current file.

To pack the JDataStore, select Tools| Pack JDataStore.

Upgrading the JDataStore file

The JDataStore Explorer opens older versions of the JDataStore file format. The only available operation is to upgrade the file to the current version. Upgrading the JDataStore file renames the existing file (by prepending "BackupX_of_" where X is an auto-incrementing number), and it copies all the streams from the old file to a new version of the current file.

To upgrade the JDataStore, select Tools |Upgrade JDataStore. When the current JDataStore is the current version, this menu option is disabled.

Deleting the JDataStore file

You can use the JDataStore Explorer to delete a JDataStore file and its transaction log files. To use this feature, you must open the JDataStore file you want to delete. Then select Tools| Delete JDataStore. A confirmation dialog box appears. Click Yes to delete the JDataStore file(s).


JDataStore security tasks

The following security-related tasks can be performed using the JDataStore Explorer:

Administering Users

To administer users for a JDataStore, select Tools|Administer Users. If an administrator has not previously been defined for the JDataStore, when you select this menu option, a dialog will prompt for the administrator's user name and password. When you choose an administrator user name and password, the administrator user will automatically be added and will be assigned all rights for the JDataStore by default.

If you are logged in as a user with administrator's rights, the Administer Users dialog appears. If a user without administrator's rights tries to open this dialog, they will be prompted for an administrator's user name and password. The Administer Users dialog allows the administrator to add, edit, and remove users, and assign rights to each user. Here is the Administer Users dialog:

The existing users are displayed in a table. Checkboxes in the table columns indicate which rights are assigned to a user. For an explanation of the various rights, see "Authorization".

Adding a user

To add a user, click the Add button on the Administer Users dialog. You will see the Add User dialog, which looks like this:

Enter a name for the new user. Type in the user's password, and then type it again to confirm the password. The user will be able to change their own password when they log in.

Next, select which rights the user will have. For an explanation of the various rights, see "Authorization". Click OK when you are done assigning rights to the user.

Editing a user

To edit a user, select the row for the user in the table, then click the Edit button on the Administer Users dialog. You can now edit the rights for the selected user. The Edit User dialog appears very similar to the Add User dialog, except you cannot edit the user name or password.

Removing a user

To remove a user, select the row for the user in the table, then click the Remove button on the Administer Users dialog. You will be prompted to confirm that you want to remove the user. You cannot remove the only administrator.

Changing a password

A user must be currently logged in to change their password. To change the password for the current user, select Tools|Change Password. A Change Password dialog is presented. You must enter the old password, then enter the new password twice for confirmation. Click OK.

Encrypting a JDataStore

To encrypt a JDataStore file, select Encrypt JDataStore from the Tools menu. The JDataStore Explorer will try to encrypt the JDataStore immediately. A message will then indicate success or failure. If the JDataStore is encrypted successfully, a backup copy of the original file will be made, and the results message will indicated the name of this backup.