JDataStore 3.51 Hints and Tips
Introduction
JDataStore is a high-performance, small-footprint, 100% Pure JavaTM multi-faceted
data storage solution. It is:
-
A zero-administration embedded relational database, with both JDBC and
DataExpress interfaces, that supports transactional multi-user access with
crash recovery.
-
An object store, for storing serialized objects, tables, and other file
streams.
-
A JavaBean component, that can be manipulated with visual bean builder
tools like JBuilder.
JDataStore can function as a server or be embedded into "client-side" or
remote applications with top performance and virtually zero administration.
As a more cost effective database solution than competitors, JDataStore
is a complete solution for all-Java platforms including: mobile computing,
Internet applications, Web servers and Enterprise JavaBean (EJB) servers.
Other key features include object relational storage, Pure Java Database
Connectivity (JDBC) local or remote Type 4 drivers, JavaBean components
that allow direct access to JDataStore, and lightweight replication and
synchronization technology. All of these features enable JDataStore
to solve a variety of general database problems and complement popular
native RDBMS systems like InterBase, Oracle, DB2, MS SQL Server and Sybase.
Contents
JDataStore Web Site
For the latest information about JDataStore, see http://www.borland.com/jdatastore/
[top]
Minimum System Requirements
-
JDK 1.2.2
-
16MB RAM
-
32MB hard disk space for installation
Windows
-
JDK 1.2.2
-
Intel Pentium 133MHz or compatible
-
Microsoft Windows 98 or NT 4.0 (SP3)
Linux
-
Intel Pentium 133MHz or compatible
-
RedHat 6.x, Mandrake 6.x, 7.0 (recommended)
-
glibc 2.1.1 or above and Kernel 2.2.5 or above
Solaris
-
ULTRASparcTM 2
-
Solaris 2.6 or Solaris 7 (2.7)
Deployment
-
JDK 1.1.x or JDK 1.2.2 (recommended)
[top]
JDataStore Documentation
The JDataStore 3.51 documentation is available as a separate download.
See http://www.borland.com/techpubs/jdatastore/
for information on downloading, installing and viewing the JDataStore documentation.
[top]
JDataStore Tools and Samples
JDataStore 3.51 also provides several tools and samples that assist you
in using JDataStore. See the installation instructions for your platform
for information on starting and using these tools.
JDataStore Explorer
Using the all-Java DataStore Explorer, you can:
-
Examine the contents of a DataStore. The DataStore's directory is shown
in a tree control, with each table and its indexes grouped together. When
a data stream is selected in the tree, its contents are displayed (assuming
it's a file type like text file, GIF image, or table, for which the Explorer
has a viewer).
-
Perform many DataStore operations without writing code. You can create
a new DataStore file, import delimited text files into datasets, import
files as file streams, delete indexes, delete datasets or other data streams,
and verify the integrity of the DataStore.
-
Manage queries that provide data into datasets in the DataStore, edit the
datasets, and save changes back to server tables.
To start the JDataStore Explorer on Windows, do one of the following:
-
If you are running JBuilder, select Tools | DataStore Explorer.
-
Select Start | Programs | JDataStore 3.5 | DataStore Explorer.
-
Start dse.exe in your JDataStore 3.5 bin directory.
To start the JDataStore Explorer on Linux or Solaris, do one of the following:
-
If you are running JBuilder, select Tools | DataStore Explorer.
-
Start dse.bin in your JDataStore 3.5 bin directory.
JDataStore Server
To access JDataStore files through a remote JDBC connection, a JDataStore
JDBC server must be running on a machine that has local access to those
files. This could be the actual machine that contains the files, or a machine
that has direct network access to JDataStore files on a networked drive.
To start the JDataStore Server on Windows, do one of the following:
-
If you are running JBuilder, select Tools | DataStore Server.
-
Select Start | Programs | JDataStore 3.5 | DataStore Server.
-
Start dss.exe in your JDataStore 3.5 bin directory.
To start the JDataStore Server on Linux or Solaris, do one of the following:
-
If you are running JBuilder, select Tools | DataStore Server.
-
Start dss.bin in your JDataStore 3.5 bin directory.
JDBC Explorer
The JDBC Explorer is a hierarchical database browser that also allows you
to edit data. It presents JDBC-based meta-database information in a two-paned
window.
-
The left pane contains a tree that hierarchically displays a set of databases
and its associated tables, views, stored procedures, and metadata.
-
The right pane is a multi-page display of descriptive information for each
node of the tree. In certain cases, you can edit data in the right pane
as well.
To start the JDBC Explorer on Windows, do one of the following:
-
If you are running JBuilder, select Tools | JDBC Explorer.
-
Select Start | Programs | JDataStore 3.5 | JDBC Explorer.
-
Start jdbce.exe in your JDataStore 3.5 bin directory.
To start the JDBC Explorer on Linux or Solaris, do one of the following:
-
If you are running JBuilder, select Tools | JDBC Explorer.
-
Start jdbce.bin in your JDataStore 3.5 bin directory.
When you run JDBC Explorer from within JBuilder, it can access class and
jar files that you have made available in JBuilder through entries in JBuilder.config.
If you will run JDBC Explorer standalone, add the class or jar for your
database's driver to jdbce.config, in your JBuilder 3.5 or JDataStore
3.5 bin directory. Follow the pattern of the DataStore's
remote driver, which is defined there in the "Database drivers" section.
JDataStore Samples
Sample programs showing how to create and work with JDataStore files are
included in the JDataStore\Samples directory. These samples include:
-
JDataStore Demo: A demonstration of the speed of adding rows to
a parent and child table in a JDataStore. A recent article in JBuilder
Developers Journal, http://www.sys-con.com/jbuilder/1-1/shaughnessy,
provides more details on this demo. To see the demo, run samples/jdatastore/Basics\runJDataStoreDemo.
-
JDataStore Basics: Snippets of code from the JDataStore Programmer's
Guide which show how to create and work with JDataStore files. See
samples/jdatastore/dsbasic/dsbasic.html for more information.
-
HelloJDBC: A simple sample showing how to work with JDataStore files
using the JDataStore JDBC drivers. See samples/jdatastore/HelloJDBC.
-
WebBench: WebBench is a multi-threaded framework that shows how
to establish concurrent connections to a transactional datastore. It demonstrates
JDataStore's ability to support large amounts of data and many concurrent
transactions. Through a simple interface, you can define a run configuration,
set it executing, and see how many transactions were executed. See samples/jdatastore/WebBench/WebBench.html
for more information.
-
Offline Editing: This sample provides the steps for creating an
application that uses a local DataStore component to enable offline editing
of data from a remote database. See samples/jdatastore/OfflineEditing/OfflineEditing.html
for more information.
[top]
What's new in JDataStore 3.51
JDataStore 3.51 features fixes to DataStore functions such as read-only
transactions and multi-threaded application support. These fixes have resulted
in significantly better reliability, more consistent operation on all platforms,
and improved recovery from system failures. Stressful applications -- those
that run for a long time, access the DataStore heavily, or execute competing
transactions from multiple users concurrently -- run better than in previous
versions of JDataStore. Performance has also been improved slightly.
For this release, basic functionality test suites and stress tests have
has been executed on Windows NT, Solaris, and Linux using the JDK 1.2.2
provided with JBuilder 3.5. Because no Java 2 APIs are used at runtime,
this release also supports JDK 1.1.x. Basic tests suites have been run
on JDK 1.1.8.
The JDataStore JAR files in this release have the same names as they
did in JBuilder 3 - Solaris Edition and JBuilder 3.5, for instance "datastore3.1.jar".
However, they have a new internal version number, "300.500.032.000". To
display the JAR version numbers
-
Open jbuildnum.txt in your JBuilder folder. If the file was not
installed, you do not have the latest version.
-
Select Help | About from the DataStore Explorer's menu
-
Call com.borland.dbtools.common.DbVersion's getImplementationVersions()
method
This will tell you which release of JDataStore 3.5 you have. Don't rely
on the version number on the JBuilder splash screen and About dialog, which
will be the same whether you have the JDataStore 3.51 or an earlier version.
[top]
Storage of date/time values
In JBuilder 3 and JBuilder 3.5, JDataStore stores date and time values
as the local time in the time zone where the values were entered.
This has been changed; for newly created DataStores, JDataStore now follows
the Java convention in storing date/time values as GMT time. Because java.sql.Date,
Time, and Timestamp objects take care of conversion to local time, there
will be no visible difference in most applications. DataStores with the
new date/time handling will use a new version of the DataStore file format,
version 5.
Effects of changed date/time storage
The new date/time storage will only be visible in applications that work
with dates and times in multiple time zones. A DataStore file of the previous
version, version 4, displays date/time values as the local time in the
time zone where the data was entered, regardless of the time zone where
the data is being displayed. For example, if the time 10:00 AM is entered
in the Pacific Standard time zone, it will also be displayed as 10:00 AM
in the Eastern Standard time zone (and every other time zone). A version
5 store file, on the other hand, adjusts date/time values according to
the time zone in which the data is displayed. Different time zones
display the same data differently, each giving the local time representation
of the same instant in time. To use the same example, the time that's displayed
as 10:00 AM Pacific Standard Time will now be displayed as 1:00 PM Eastern
Standard Time.
You only need to be concerned with this change in a few cases:
-
If you created a version 4 store in one time zone and moved it to another:
To get the correct conversion, set your computer's time zone to the time
zone where the store was created before upgrading it.
-
If your application contains date/time values entered from more than one
time zone: The upgrade to a version 5 store can only be sensitive to one
time zone, so it cannot upgrade all the data in this store correctly.
-
If your application runs in several time zones and relies on date/time
values being the local time at the point of data entry: You will have to
rework application code to use version 5 stores. It is likely that the
data values don't truly represent date/times and can better be stored as
numbers or strings.
Effects of new DataStore file version
JDataStore 3.51 handles dates and times in version 4 DataStores just as
the previous releases do. Any new DataStore you create will be a version
5 store and will use the new rules for storing date/time values.
JDataStore 3.51 automatically converts from the old representation to the
new when you upgrade a version 4 store or copy data from a version 4 store
to a version 5 store. You can check a DataStore's version or upgrade a
version 4 store to version 5 through the DataStore Explorer.
Previous JDataStore releases can't open version 5 stores. If some users
of an application have upgraded to JDataStore 3.51 while others have not,
the application's DataStores must be version 4 files. For simplicity and
to take advantage of improved performance and reliability, it is preferable
to provide all users with JDataStore 3.51 and upgrade the store files to
version 5.
DataSetData version
Because they may store date/time values, DataSetData objects created by
JDataStore 3.51 will also have a new version number. This is not likely
to be a problem. Normally, the same JDataStore JARs are on the classpath
of the code that loads a DataSetData object and the code that extracts
from it, and the DataSetData objects themselves are usually not long-lived.
[top]
soTimeout property
A new property, soTimeout, has been added to DataStoreServer. Use soTimeout
to specify the time, in milliseconds, that the DataStore server should
wait for a connection to be made before checking if a shutdown request
has been made. soTimeout defaults to 0, meaning that it will wait indefinitely
for the connection to be made. You will probably only want to set it if
you are running on an unusual platform or JDK version and your DataStoreServer
will not shut down.
[top]
Moving log files
Moving transactional DataStores is now easier than documented in the JDataStore
Programmer's Guide, even when you move then from one device to another.
Simply move the DataStore and its log files to the new location. (If you
want to copy it, you'll have to rename the log files in the original location
at least temporarily.) When you open a transactional
DataStore, JBuilder's rules are:
-
If the log files are found where the DataStore says they will be, they
are used. (In this example, the DataStore will expect to find the log files
are in the original location, but they won't be there.)
-
If log files of the correct names are found in the same directory as the
DataStore file, they are used, and the store is updated to expect them
there in the future. (This will happen in this example.)
-
If log files are found in both locations, the store cannot be opened.
-
If the store file says the logs files are on a non-existent device, JBuilder
will look in the store directory instead. This allows you to move DataStores
without worrying where they were located originally.
Surprisingly, disabling transactions before you move or copy a DataStore
can introduce complications. If you make a DataStore non-transactional
in order to truncate the log, consider making it transactional again before
you move it. These operations can be done from the DataStore Explorer's
TxManager menu.
[top]
WebBench sample application
The WebBench sample application, in samples/JDataStore/WebBench under your
JBuilder directory, demonstrates JDataStore's ability to support large
databases and many concurrent transactions. It shows how to establish concurrent
connections to a transactional DataStore, and it can be used to benchmark
JDataStore's performance running realistic complex transactions.
Ignore the corrections mentioned in JBuilder's hints_and_tips.html.
The JDataStore 3.51 version of WebBench is ready to run. It has several
small new features that are not described in its documentation:
-
You can save WebBench's execution log to a text file by right-clicking
in the main text area and selecting Save Log. The text file is written
to the directory specified in the File Path option and is named WebBench.log.
It is saved automatically when you exit.
-
The log now displays the number of SQL statements executed as well as the
number of transactions.
[top]
Application deployment
Information on deploying the JDataStore JDBC server for remote access is
in "Deploying the DataStore JDBC server" in the JDataStore Programmer's
Guide. Tips for reducing the deployed size of JDataStore client applications
can be found in "Pruning deployed resources" in the JDataStore Programmer's
Guide.
Reminder: JDataStore is provided with a license for development
only. To deploy JDataStore and DataExpress libraries with your application,
a deployment license must be purchased. For more information on purchasing
a JDataStore deployment license, see www.borland.com/jdatastore.
Only the following JDataStore libraries may be deployed with your application
when you purchase a JDataStore deployment license:
-
dx3.1.jar
-
datastore3.1.jar
-
dsserver3.1.jar
-
dsremote3.1.jar
[top]