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.
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:
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 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 boolean isOpen()Read-only property that returns whether the connection to the DataStore is open (true) or not (false).
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).
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 StoreInternals getStoreInternals()This property is used internally by other com.borland classes.
public final int getTxIsolation() public final void setTxIsolation(int isolation)Transaction isolation level for this connection. DataStore supports:
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.
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.
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.
public final synchronized FileStream createFileStream(String storeName)Creates a new FileStream inside the DataStore using storeName for the directory entry.
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).
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.
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.
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.
public final synchronized StreamProperties getStreamProperties(ReadRow dirEntry)Returns a StreamProperties object for a stream. On error, this method throws a DataSetException.
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 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.
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.
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));
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.
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.
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.
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.
public final boolean tableExists(String storeName)Returns true if a table stream with the specified storeName exists.
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.
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.