borland Packages Class Hierarchy datastore Package
java.lang.Object +----com.borland.datastore.DataStoreConnection +----com.borland.datastore.DataStore
Variables Constructors Properties Methods
Implements Designable, Store
A DataStoreConnection
is used to access a DataStore
.
Multiple DataStoreConnection
objects can connect to the same
DataStore
from the same process. Each connection provides a
separate transactional context.
Because the DataStore
subclasses
DataStoreConnection
, each DataStore
has its own
built-in connection. If you only need a single connection, you can
instantiate the DataStore
object, and use the connection
through the properties and methods inherited from
DataStoreConnection
. This technique is more likely if you are
creating the DataStore
file, or when you are setting the
physical properties of the DataStore
itself.
You do not need to instantiate a DataStore
object to access
a DataStore
file; the DataStoreConnection
will do this
for you automatically, opening a connection to the DataStore
file specified in the fileName
property.
DataStoreConnection
implements the Store
interface, so
it can be used in the store
property setting of a
StorageDataSet
.
DataStoreConnection
object.
fileName
property of the
DataStoreConnection
.
userName
property.
open
method.
A transactional DataStore
is one that was created with a
TxManager
(the transaction manager). Once a DataStore
is created, it remembers whether it is transactional and where its log
files are kept, so that when it is opened again later, a
TxManager
will be instantiated automatically if necessary.
The rollback
method will undo all changes made in the current
connection since the last rollback()
or commit()
and
terminate the transaction.
A number of methods use a dirEntry
parameter to indicate
which stream to operate upon. This parameter is of the type
com.borland.dx.dataset.ReadRow
, and is usually an instance of
one of its subclasses:
StorageDataSet
returned by the openDirectory
method.
DataSetView
of such a StorageDataSet
.
DataRow
constructed from a row in one of those other
DataSets.
For a DataSet with more than one row, the action is performed upon the stream identified by the current row.
public static final int COPY_CASE_SENSITIVE = 0x2By default all match comparisons for the
sourcePattern
parameter to copyStreams()
are case-insensitive. When this is
used in the option
parameter, matches use strict
case-sensitivity.
public static final int COPY_IGNORE_ERRORS = 0x4By default any errors that are encountered during
copyStreams
terminate the copy operation. If this option is set, the copy operation
will skip the stream that cannot be copied and attempt to copy the
remaining streams. The name of the stream that caused the error and an
exception stack trace will be sent to the output status stream (if one
is specified).
public static final int COPY_OVERWRITE = 0x1When used in the
option
parameter of copyStreams()
,
existing streams will be overwritten. By default, a
DataStoreException
will be thrown if the target stream already
exists.
public DataStoreConnection()Constructs a
DataStoreConnection
component. To connect to a
DataStore
, set the fileName
property and call the
open()
method.
public final int getCacheSize()Returns the size of the
Cache
.
public final DataStore getDataStore()Read-only property that returns an object representing the currently connected
DataStore
, or null if no connection is open.
public final String getFileName() public final synchronized void setFileName(String fileName)Specifies the String name of the
DataStore
file to connect to.
If the DataStoreConnection
is open when the setFileName()
method is called, a DataSetException
is thrown.
If the DataStore
's
tempDirName
property is not set, temporary files are created in the directory
location of fileName
.
public Locale getLocale()Returns the locale associated with the connected
DataStore
. To
set the locale, you must access the locale
property
of the DataStore
.
This is the default locale setting for StorageDataSet
objects that do not have a locale setting.
public final long getLockWaitTime() public final void setLockWaitTime(long waitTime)Determines the amount of time, in milliseconds, that the connection waits for a lock before aborting the current transaction. This is also used for deadlock detection. Setting this property to zero causes the connection to wait indefinitely. The default value is 10000 (10 seconds).
This property has no effect when the DataStore
is not
transactional.
public final int getMinCacheSize() public final void setMinCacheSize(int size)Sets the number of cache blocks in the cache. Note that all DataStores share the same cache.
public final boolean isOpen()Read-only property that returns whether the connection to the
DataStore
is open (true) or not (false).
public final String getPassword() public final void setPassword(String pass)Does not return the password. Property can be written, but not read. Set password name for this connection.
public final boolean isProtected()Returns true if the user for this connection is password protected.
public final boolean isReadOnly() public final void setReadOnly(boolean readOnly)When set, only read access is allowed for this DataStore.
public final boolean isReadOnlyTx() public final void setReadOnlyTx(boolean readOnlyTx)Enables read-only mode on this connection. This property must be set before you open the connection. If true, when the connection opens, it will see a snapshot of all data, such that:
DataStore
.
To refresh the snapshot of data, call the commit
method for
the connection (this starts a new read-only transaction).
public final long getReadOnlyTxDelay() public final void setReadOnlyTxDelay(long lagTime)
When the readOnlyTx
property is true, the
connection gets a snapshot of the DataStore data when it opens (or
refreshes). This property specifies how long to hold onto a given
snapshot, in milliseconds, so that it can be shared by other read-only
connections. Sharing snapshots improves performance. Once the
lagTime
period ends, the next read-only transaction that opens
(or refreshes) will get a new snapshot.
A value of 0 indicates there should be no delay, and that the connection should always check for the latest data.
public final int getRights()Combination of values in
DataStoreRights
or'd together.
public final StoreInternals getStoreInternals()This property is used internally by other
com.borland
classes.
public final String getTempDirName() public final void setTempDirName(String tempDirName)Directory for temp files. Used for operations like large sorts. If this is not set, the directory of the DataStore.Name property will be used for temporary files.
public final int getTxIsolation() public final void setTxIsolation(int isolation)Transaction isolation level for this connection. DataStore supports:
java.sql.connection
.
public final String getUserName() public final void setUserName(String userName)The name of the user associated with this connection. The name is required when connecting to a trasactional
DataStore
.
public final synchronized int getVersion()Returns the
DataStore
file version, encoded in the following
four bytes (from low byte to high byte):
Byte | Meaning |
---|---|
0 | Not used |
1 | Major product version |
2 | Minor product version |
3 | Minor file version |
If no DataStore
is open, a
DataStoreException.DATASTORE_NOT_OPEN
exception is thrown.
getProductVersion
method
public final void addUser(String adminPass, String name, String pass, int rights)Add a user to the /SYS/USERS table.
Parameters:
public final boolean canWrite()This method can be used to determine if any write operations are allowed on this connection.
public final void changePassword(String oldPassword, String newPassword)Change password for this connection.
Parameters:
public final void changeRights(String adminPass, String name, String pass, int newRights)Change the rights of a user in the
/SYS/USERS
table.
Parameters:
DataStoreRights.ADMINISTRATOR
rights.
DataStoreRights
or'd together.
DataStoreRights.STARTUP
rights to a user.
public void close()Closes the connection to the
DataStore
component and flushes
the data cache. All pending changes are committed. If it was the last
connection to the DataStore
the DataStore
will
shutdown.
On failure, this method throws a DataSetException
. If an
IOException
is generated, it is returned in the chained
DataSetException
object.
public final synchronized void closeDirectory()Closes the directory
StorageDataSet
(returned by the
openDirectory
method) that contains information on the
directory structure of the DataStore's file system.
In addition to releasing memory resources, closing the directory before directory update operations may improve their performance.
openDirectory
method
public final synchronized void closeStream(String storeName)Forces the stream named
storeName
to close. Normally, table
streams are closed through the accessing API (DataExpress or JDBC), and
file streams are closed by calling the close
method of the
FileStream
object returned by createFileStream
or
openFileStream
. Calling closeStream
bypasses these
normal usage conventions and closes the stream at the source; further
attempts to access the stream (without reopening new connections) will
result in an appropriate exception.
public final boolean commit()Commits all the changes made through the connection since the last
commit()
or rollback()
.
Returns true if successful, or
false if there was no work to commit, or if the
connection's readOnlyTx
property has been set.
public final void copyStreams(String sourceDir, String sourcePattern, DataStoreConnection destCon, String destDir, int options, PrintStream out)Copies all or part of one
DataStore
to another. The copy
operation will attempt to repair any damaged streams and copy them
correctly. If a stream cannot be copied, copyStreams
will
either stop, or ignore the current stream and copy the rest (if any),
depending on whether COPY_IGNORE_ERRORS is specified as one of the
options
.
Each stream is identified with a name that uses the "/" character as
a directory separator to simulate a hierarchical directory structure.
But copyStreams
treats the name as a simple, single string.
The sourceDir
and destDir
are useful primarily when
changing directories during the copy; otherwise these two parameters
should be specified as empty strings. The sourcePattern
is
compared against the part of the name that comes after the
sourceDir
; if sourceDir
is empty, then
sourcePattern
is compared against the entire name.
If a stream already exists with the target name in the destination
DataStore
, the default action is to throw a
DataSetException
. You can choose to overwrite existing
streams instead by specifying COPY_OVERWRITE as one of the options
.
sourceDir
destDir
name in the copy.
sourcePattern
storeName
of stream or streams to copy, using
the standard '*' (multiple character) and '?' (single character)
wild cards. By default, the name match is case-insensitive. You
can make it case-sensitive by specifying COPY_CASE_SENSITIVE as
one of the options
.
destCon
DataStore
to copy to. You
may specify a connection to the same DataStore
, or even
use the same DataStoreConnection
, as long as the
sourceDir
and destDir
parameters are
different to make a copy of a stream inside the same
DataStore
.
destDir
sourceDir
).
options
DataStoreConneciton.COPY_*
options, or
zero to use the default options.
out
PrintStream
(if
not null).
public final void copyUsers(DataStoreConnection con, String adminPass, boolean copyEncryption)Copy users table to a DataStore that does not have a user table.
Parameters:
public final synchronized FileStream createFileStream(String storeName)Creates a new
FileStream
inside the DataStore
using storeName
for the directory entry.
openFileStream
method
public final synchronized void deleteStream(String storeName)Deletes the named file from the
DataStore
. To restore the file (if possible), use the
undeleteFile()
method.
public final synchronized boolean dropIndexStream(ReadRow dirEntry)Deletes a secondary index stream (
DataStore.SECOND_INDEX_STREAM
).
associated with a table stream (DataStore.TABLE_STREAM
).
dirEntry
DataStore.DIR_TYPE
column
should be of type DataStore.SECOND_INDEX_STREAM
.
public final synchronized void dumpLocks(PrintStream out)Displays information for all locks current held by the connection to the designated output.
public final synchronized void dumpTxLog(PrintStream out, long startLsn)Displays the contents of DataStore's transactional log file in text format.
out
startLsn
public final void encrypt(String adminPass, String masterKeySeed, int encrypt)Encrypt the database file. This method cannot be called until at least one user with DataStoreRights.ADMINISTER has been added with the DataStoreConnection.addUser() method.
Parameters:
See also: Encrypt
See also: DataStoreConnection.addUser
public final boolean fileExists(String storeName)Returns true if a file stream with the specified
storeName
exists, false if it doesn't exist.
On error this method throws a DataSetException
.
tableExists
method
public final synchronized long fileLength()
Returns: The length of the JDataStore file in bytes.
public void finalize()Closes the DataStore connection if it is still open.
public static final String getProductVersion()Returns the version of the
DataStore
package; not to be
confused with the version
property, which is the version of
the open DataStore
file.
version
property
public final synchronized StreamProperties getStreamProperties(ReadRow dirEntry)Returns a
StreamProperties
object for a stream. On error, this
method throws a DataSetException
.
dirEntry
StreamProperties
class
This code fragment scans through the streams in a DataStore, looking for an index stream with a particular name.
String indexName = "NameToFind"; TableDataSet storeDirectory = (TableDataSet) dataStore.openDirectory(); // This creates the structure of the row only DataRow dirEntry = new DataRow(storeDirectory); // Scan directory for secondary index entry while (storeDirectory.inBounds()) { if (storeDirectory.getShort(DataStore.DIR_TYPE) == DataStore.SECOND_INDEX_STREAM) { // Copy the actual data to the DataRow storeDirectory.copyTo(dirEntry); streamProperties = dataStore.getStreamProperties(dirEntry); Diagnostic.println("IndexName=" + streamProperties.getIndexName()); if (streamProperties.getIndexName().equals(indexName)) { break; } } storeDirectory.next(); } Diagnostic.println("Found=" + streamProperties.getIndexName());
public final synchronized void lockTableStream(String storeName)Locks a table stream.
public final void open()Opens a connection to a
DataStore
using the fileName
property to locate and open the DataStore
. If the
DataStore
is transactional, then the userName
property
must also be set before opening. When a StorageDataSet
that
uses a DataStore
is opened, it automatically asks the
DataStore
to open. This method generates a
DataStoreException
of DATASTORE_NOT_FOUND
or an
IOException
if appropriate.
close
method,
DataStore.create
method
public final StorageDataSet openDirectory()Returns information on the directory structure for this
DataStore
as a list of table and file streams in the
DataStore
. This information is returned as rows in a
StorageDataSet
component. On failure, this method throws a
DataSetException
.
The returned StorageDataSet
is sorted by the first five of
its columns as follows:
Column | Type | Description |
---|---|---|
State | short | Describes the state of the stream, comprising a valid combination of one or more DataStore.*_STATE values. |
DeleteTime | long | UTC time a stream was deleted. If the stream has not been deleted, this value is always 0. |
StoreName | String | Name for the stream, 1 to 192 bytes long. |
Type | short | Describes the stream type, one of the DataStore.*_STREAM values. |
Id | int | A unique identifier for a stream. |
Properties | String | Lists persisted properties/events for a DataSet stream.
|
ModTime | long | UTC time the stream was last modified. |
Length | long | Length of the stream in bytes. |
BlobLength | long | Length of a table stream's BLOBs, in bytes. |
The names of these columns are defined as DIR_*
constants
in the DataStore
class; for example, DIR_STATE is the string
"State". Using these constants provides compile-time checking that the
proper column name has been used.
This code fragment uses the directory returned by
openDirectory
to undelete a stream.
TableDataSet storeDirectory = (TableDataSet) dataStore.openDirectory(); // Before deleting Diagnostic.println("Stream exists: " + dataStore.fileExists(streamName)); dataStore.deleteStream(streamName); Diagnostic.println("Stream exists: " + dataStore.fileExists(streamName)); // This creates the structure of the row only DataRow dirEntry = new DataRow(storeDirectory); // Find the entry in the DataSet dirEntry.setString(DataStore.DIR_STORE_NAME, streamName.toUpperCase()); storeDirectory.locate(dirEntry, Locate.FIRST); // And copy the actual data to a new DataRow storeDirectory.copyTo(dirEntry); Diagnostic.println("Undeleting=" + storeDirectory.getString(DataStore.DIR_STORE_NAME)); dataStore.undeleteStream(dirEntry); Diagnostic.println("Stream exists: " + dataStore.fileExists(streamName));
closeDirectory
method
public final synchronized FileStream openFileStream(String storeName)Opens an existing
FileStream
. Although FileStream
extends java.io.InputStream
, it also provides seek()
and write()
methods. This method throws a
DataStoreException
of FILE_NOT_FOUND
if the stream
does not exist.
createFileStream
method
public final synchronized Object readObject(String storeName)Retrieves a Java Object from a
DataStore
using Java
serialization. The Object must implement java.io.Serializable
;
and its class must be accessible, or a ClassNotFoundException
will be thrown.
writeObject
method
public final void removeUser(String adminPass, String name)Remove a user from the /SYS/USERS table.
Parameters:
public final synchronized void renameStream(String storeName, String newStoreName)Renames a stream from
storeName
to newStoreName
. If
there is no stream with the original name storeName
, nothing
happens.
public final boolean rollback()Rolls back all the changes made through the connection since the last
commit()
or rollback()
.
Returns true if successful, or
false if there was no work to roll back, or if the
connection's readOnlyTx
property has been set.
public void sortTable(String source, String dest, SortDescriptor descriptor)Makes a new sorted copy of a table stream. Note that the order of the new sorted table is not automatically maintained when it is edited; it's simply a new table that happens to have its rows in a particular order. To maintain the sort order, use the
sort
property of the
DataSet.
source
storeName
of the table to sort and copy
dest
storeName
of the new table to create
sortDescriptor
public final boolean tableExists(String storeName)Returns true if a table stream with the specified
storeName
exists.
fileExists
method
public final boolean transactionStarted()Returns true if a transaction has been started; that is, if any changes have been made since the last
commit()
or
rollback()
.
public final synchronized boolean undeleteStream(ReadRow dirEntry)Undeletes a deleted stream if its space has not been reallocated to other active streams. On error, this method throws a
DataSetException
.
dirEntry
public final synchronized void writeObject(String storeName, Object object)Stores a Java Object into the
DataStore
(using Java
serialization) as a file stream with the name storeName
. The
Object must implement java.io.Serializable
.
readObject
method