borland Packages  Class Hierarchy  datastore Package 

DataStoreConnection component

java.lang.Object
   +----com.borland.datastore.DataStoreConnection
           +----com.borland.datastore.DataStore

About the DataStoreConnection component

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.

Opening a Connection

The minimum steps for opening a connection to a DataStore are:
  1. Instantiate a DataStoreConnection object.
  2. Set the fileName property of the DataStoreConnection.
  3. If the DataStore is transactional, you must also set the userName property.
  4. Call its open method.

Managing Transactions

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.

Directory Entry Parameters

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:

For a DataSet with more than one row, the action is performed upon the stream identified by the current row.


DataStoreConnection variables

Variables implemented in this class

DataStoreConnection constructors

DataStoreConnection properties

*Read-only properties **Write-only properties

Properties implemented in this class

Properties implemented in java.lang.Object

DataStoreConnection methods

Methods implemented in this class

Methods implemented in java.lang.Object


DataStoreConnection variables

COPY_CASE_SENSITIVE

  public static final int COPY_CASE_SENSITIVE = 0x2
By 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.

COPY_IGNORE_ERRORS

  public static final int COPY_IGNORE_ERRORS = 0x4
By 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).

COPY_OVERWRITE

  public static final int COPY_OVERWRITE = 0x1
When 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.

DataStoreConnection constructors

DataStoreConnection()

  public DataStoreConnection()
Constructs a DataStoreConnection component. To connect to a DataStore, set the fileName property and call the open() method.

DataStoreConnection properties

dataStore

 public final DataStore getDataStore()
Read-only property that returns an object representing the currently connected DataStore, or null if no connection is open.

fileName

 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.

locale

 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.

lockWaitTime

 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.

open

 public final boolean isOpen()
Read-only property that returns whether the connection to the DataStore is open (true) or not (false).

readOnlyTx

 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:

To refresh the snapshot of data, call the commit method for the connection (this starts a new read-only transaction).

readOnlyTxDelay

 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.

storeInternals

 public final StoreInternals getStoreInternals()
This property is used internally by other com.borland classes.

txIsolation

 public final int getTxIsolation()
 public final void setTxIsolation(int isolation)
Transaction isolation level for this connection. DataStore supports: as defined in java.sql.connection.

userName

 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.

version

 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.

See also: getProductVersion method


DataStoreConnection methods

close()

  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.

closeDirectory()

  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.

See also: openDirectory method

closeStream(java.lang.String)

  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.

commit()

  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.

copyStreams(java.lang.String, java.lang.String, com.borland.datastore.DataStoreConnection, java.lang.String, int, java.io.PrintStream)

  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.

Parameters:

sourceDir
The directory to copy from. This directory will be replaced with the destDir name in the copy.
sourcePattern
The 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
A connection to the 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
The directory to copy to. The name of the copied stream will be prefixed with this string (after stripping off the old sourceDir).
options
Any of the DataStoreConneciton.COPY_* options, or zero to use the default options.
out
Status messages are routed to this PrintStream (if not null).

createFileStream(java.lang.String)

  public final synchronized FileStream createFileStream(String storeName)
Creates a new FileStream inside the DataStore using storeName for the directory entry.

See also: openFileStream method

deleteStream(java.lang.String)

  public final synchronized void deleteStream(String storeName)
Deletes the named file from the DataStore. To restore the file (if possible), use the undeleteFile() method.

dropIndexStream(com.borland.dx.dataset.ReadRow)

  public final synchronized boolean dropIndexStream(ReadRow dirEntry)
Deletes a secondary index stream (DataStore.SECOND_INDEX_STREAM). associated with a table stream (DataStore.TABLE_STREAM).

Parameters:

dirEntry
The directory entry for the index stream to delete. The DataStore.DIR_TYPE column should be of type DataStore.SECOND_INDEX_STREAM.

dumpLocks(java.io.PrintStream)

  public final synchronized void dumpLocks(PrintStream out)
Displays information for all locks current held by the connection to the designated output.

dumpTxLog(java.io.PrintStream, long)

  public final synchronized void dumpTxLog(PrintStream out, long startLsn)
Displays the contents of DataStore's transactional log file in text format.

Parameters:

out
Destination for output.
startLsn
Starting log sequence number. Use 0 to start at the earliest point in the current set of logs.

fileExists(java.lang.String)

  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.

See also: tableExists method

finalize()

  public void finalize()
Closes the DataStore connection if it is still open.

Overrides: java.lang.Object.finalize()

getProductVersion()

  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.

See also: version property

getStreamProperties(com.borland.dx.dataset.ReadRow)

  public final synchronized StreamProperties getStreamProperties(ReadRow dirEntry)
Returns a StreamProperties object for a stream. On error, this method throws a DataSetException.

Parameters:

dirEntry
The directory entry for the desired stream.

See also: StreamProperties class

Example:

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());

open()

  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.

See also: close method, DataStore.create method

openDirectory()

  public final synchronized 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.

Example:

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));

See also: closeDirectory method

openFileStream(java.lang.String)

  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.

See also: createFileStream method

readObject(java.lang.String)

  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.

See also: writeObject method

renameStream(java.lang.String, java.lang.String)

  public final 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.

rollback()

  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.

sortTable(java.lang.String, java.lang.String, com.borland.dx.dataset.SortDescriptor)

  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
The storeName of the table to sort and copy
dest
The storeName of the new table to create
sortDescriptor
Describes the columns, order, and case-sensitivity of the sort.

tableExists(java.lang.String)

  public final boolean tableExists(String storeName)
Returns true if a table stream with the specified storeName exists.

See also: fileExists method

transactionStarted()

  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().

undeleteStream(com.borland.dx.dataset.ReadRow)

  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.

Parameters:

dirEntry
The directory entry for the stream to (attempt to) undelete.

writeObject(java.lang.String, java.lang.Object)

  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.

See also: readObject method