JDataStore is a feature of JBuilder Professional and Enterprise, and the Inprise Application Server.
Using the all-Java JDataStore Explorer, you can:
Perform many JDataStore operations without writing code. You can create a new JDataStore file, create tables and indexes, import delimited text files into datasets, import files as file streams, delete tables and indexes, delete datasets or other data streams, and verify the integrity of the JDataStore.
Manage queries that provide data into datasets in the JDataStore, edit the datasets, and save changes back to server tables.
Administer security features of a JDataStore, such as users, passwords, and encryption.
From JBuilder use the Tools|JDataStore Explorer menu command.
From the JDataStore Server (see "Running the JDataStore Server") use the File|JDataStore Explorer menu command.
From the command line or with a shortcut.
These files are also required if you want the online help to be available:
jb_ui.jar
help.jar
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:
The look and feel of the UI. One of the following:
| |
Select File|New or click the New JDataStore toolbar button. This opens the New JDataStore dialog box:
Make sure the Install TxManager check box is set properly:
For a non-transactional JDataStore, the check box should be empty
For a transactional JDataStore, the check box should be checked. You can click Properties to set the transaction management properties for the new JDataStore file.
Click OK. The store is created and opened in the JDataStore Explorer.
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.
If this occurs, follow these steps:
javaw
processes):
If there is no process that has the JDataStore file open, click Yes to reopen the JDataStore file.
If you click No, the JDataStore Explorer responds with an error dialog box that states that the file is still marked open by another process and the file won't open.
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.
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.
Whether the TxManager is installed; that is, whether the JDataStore is transactional
Whether the JDataStore file was opened read-write or read-only
A graphical representation and count of how blocks are allocated between:
Blocks formerly occupied by data that is now marked deleted and are available for reuse
Reserved blocks preallocated for future use (transactional JDataStores preallocate disk space to improve reliability)
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.
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":
This is the image file "demo/duke.gif":
Select the stream to rename/move in the directory tree. (You can't rename deleted streams. You must undelete them first.)
Type a new name in the Rename dialog box. You can't use the name of another existing active stream.
Click OK.
Undeleting a stream doesn't guarantee all the data in the stream will be recovered. See "How JDataStore reuses deleted blocks" for more details.
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.
Select Tools|Copy JDataStore. This opens the Copy Streams dialog box:
Specify the various Copy Streams options, as summarized in the following table. (For more information, see "copyStreams parameters.")
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.
Select TxManager|Install. (If the JDataStore is already transactional, that menu option will be disabled.) This opens the TxManager Properties dialog box:
The dialog box contains default settings for the TxManager
object:
You can change the default settings for the maximum number of open log files (2), maximum log file size (64MB), and checkpoint frequency (2MB).
By default, one set of log files are written in the same directory as the JDataStore file. To choose another directory, specify a different A log directory.
To maintain a second redundant set of log files, specify a B log directory.
You can enable Soft commit, which increases performance by not immediately forcing a disk write when a transaction is committed.
You can disable status logging for a slight performance improvement.
Select TxManager|Modify. (If the JDataStore is not transactional, that menu option will be disabled.) This opens the TxManager Properties dialog box.
Click OK.
To make a transactional JDataStore non-transactional, uncheck TxManager|Enabled. This immediately removes transaction support.
To close the current JDataStore file, select File|Close. To close all open JDataStore files, select File|Close All.
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.
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:
Many queries can share a connection. They all select data from the tables in the same database.
Each query creates one table. When you define and run the query in the Explorer, the resulting table is always saved in the JDataStore.
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."
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.
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.
This page lists all the tables that will be imported:
The name of the table stream that will be created in the JDataStore, which defaults to the original name. You can change this. It can include a path as in "Data/Tutorial/Employee." The Explorer's tree pane displays this as a dataset named "Employee" in a folder named "Tutorial," which in turn is in a folder named "Data."
The SQL statement used to retrieve the data, which you can edit to change the fields, conditions, and grouping.
Check boxes to control whether indexes should be created, and whether to enable refresh and save for this query. Refresh and save settings for the query are saved to the "SYS/DataStore Queries/Queries" data set. If you have read-only tables, you should not enable save. If you know the data in a table is not going to change, you should not enable refresh.
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
Delete a connection or query definition. To do so, select it and press "-" on the navigation toolbar or press Ctrl+Del.
Insert a new definition. To do so, press "+" on the navigation toolbar or press Ctrl+Ins.
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.
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.
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,
Select Tools|Import|Text Into Table. This opens the Import Delimited Text File dialog box.
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.
Click OK.
Supply an input file name and the store name of the file stream to be created.
Click OK.
Type a name for the new table in the Table Name field.
Column
class for a description of the meaning of the Column
properties.)
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.
Choose the name of the table for which you want to create an index in the Table Name drop-down list.
<null>
.
The Info tab shows the properties of the selected index.
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.
To pack the JDataStore, select Tools| Pack JDataStore.
To upgrade the JDataStore, select Tools |Upgrade JDataStore. When the current JDataStore is the current version, this menu option is disabled.
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".
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.
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.
jpgpubs@inprise.com
Copyright © 2000, Inprise Corporation. All rights reserved.