borland Packages Class Hierarchy datastore Package
java.lang.Object +----com.borland.datastore.TxManager
Variables Constructors Properties Methods
Implements Designable, Runnable
The TxManager enables transaction and crash recovery support for a DataStore. You may assign a TxManager to a DataStore before you create() or open() it. For example, if you want to use the default properties for a TxManager, all you need to make a DataStore transactional is:
dataStore.setTxManager( new TxManager() ); dataStore.open();
Whenever a DataStore is transaction-enabled the first time, it
creates a number of log files. For greater reliability, you can choose
to duplex the log files, creating two identical copies (usually in
different locations). The names of the log files use the name of the
DataStore file, without the file extension. For example, if the
DataStore file MyStore.jds
uses simplex transaction
logging, the following log files are created:
MyStore_STATUS_0000000000
,
MyStore_LOGA_ANCHOR
, and
MyStore_LOGA_0000000000
.
Duplex logging adds the files MyStore_LOGB_ANCHOR
and
MyStore_LOGB_0000000000
. Additional status and record files
are created as needed, with the log file number incrementing by one each
time. As old log files are no longer needed for active transactions or
crash recovery, they are automatically deleted. Old log files can be
saved by listening to the DataStore.response event for a
ResponseEvent.DROP_LOG notification. At that point, you can
copy out the log file to another location before it is deleted, or
cancel the event to prevent the deletion of the log file.
The location of the log files is just one of several
TxManager properties that can be chosen before assigning the
TxManager to the DataStore. The TxManager properties
are persisted inside the DataStore file and the LOG?_ANCHOR
files. These properties can be changed by instantiating a new
TxManager component, assigning the properties that you want to
change (the properties you do not touch will not be changed), setting
the DataStore.txManager property to the new TxManager,
and reopening the DataStore.
Because the TxManager properties are persisted in the DataStore file, the DataStore will automatically instantiate, configure, and use a TxManager when it opens, if a TxManager is not assigned. You can open a transactional DataStore without a TxManager by setting the DataStore's readOnly property to true before opening it.
Note that the location of the log files is persisted with the full drive and path. For example, if you want to create a transactional DataStore for later deployment to a server, you should create it in the same drive and path on your development machine as the eventual location on the server.
Making a DataStore transactional increases the inital size of the file. This preallocation of disk clusters decreases the chance of write failures and improves the chances for data recovery.
The properties and methods of TxManager configure the operation of the transaction management engine. You do not commit and roll back transactions through the TxManager; these operations are part of the DataStoreConnection class.
public static final int DEFAULT_CHECK_FREQUENCY = 1024 * 1024 * 2Default value for the checkFrequency property; also used when invalid values are assigned.
public static final int DEFAULT_LOG_BLOCK_SIZE = 4Default value for the logBlockSize property; also used when invalid values are assigned.
public static final int DEFAULT_LOG_SIZE = 1024*1024)*64Default value for the maxLogSize property; also used when invalid values are assigned.
public static final int DEFAULT_OPEN_LOGS = 2Default value for the maxOpenLogs property; also used when invalid values are assigned.
public static final int MAX_CHECK_FREQUENCY = Integer.MAX_VALUEMaximum value for the checkFrequency property. If a larger value is assigned, the property reverts to DEFAULT_CHECK_FREQUENCY.
public static final int MAX_LOG_BLOCK_SIZE = 16Maximum value for the logBlockSize property. If a larger value is assigned, the property reverts to DEFAULT_LOG_BLOCK_SIZE.
public static final int MAX_OPEN_LOGS = 16Maximum value for the maxOpenLogs property. If a larger value is assigned, the property reverts to DEFAULT_OPEN_LOGS.
public static final int MIN_CHECK_FREQUENCY = 1024 * 8Minimum value for the checkFrequency property. If a smaller value is assigned, the property reverts to DEFAULT_CHECK_FREQUENCY.
public static final int MIN_LOG_BLOCK_SIZE = 4Minimum value for the logBlockSize property. If a smaller value is assigned, the property reverts to DEFAULT_LOG_BLOCK_SIZE.
public static final int MIN_LOG_SIZE = 1024*1024)Minimum value for the maxLogSize property. If a smaller value is assigned, the property reverts to DEFAULT_LOG_SIZE.
public static final int MIN_OPEN_LOGS = 2Minimum value for the maxOpenLogs property. If a smaller value is assigned, the property reverts to DEFAULT_OPEN_LOGS.
public TxManager()Instantiates a TxManager with default property settings.
public final String getALogDir() public synchronized void setALogDir(String aLogDir)Directory location of the primary copy of the log files, referred to as the "A" log files, and the
STATUS
file, which collects
status messages. By default these are kept in the same directory as
the DataStore file.
public final String getBLogDir() public synchronized void setBLogDir(String bLogDir)Directory location of the secondary backup copy of the log files, referred to as the "B" log files. By default these are kept in the same directory as the DataStore.
Duplexing the log files will decrease performance, but increase the probability of a successful crash recovery. The only time log duplexing will benefit crash recovery is when there is media damage to the "A" log files or the "A" log files are lost, and the "B" log files are not damaged in the same locations or lost. Therefore, it's best to place the "B" log files on different media, preferably a different physical disk drive (which can also alleviate some of the performance penalty).
public int getCheckFrequency() public synchronized void setCheckFrequency(int checkFrequency)Frequency at which checkpoints are made to the log. checkFrequency is the amount of log file to be generated before starting a new checkpoint. A smaller value provides for faster crash recovery and faster-growing log files while a larger value provides for slower crash recovery and slower-growing log files.
public final boolean isEnabled() public final void setEnabled(boolean enabled)Enables or disables transaction support. enabled is true by default. If a transactional dataStore is opened with its txManager property set to a TxManager that has enabled set to false, the DataStore will become non-transactional. This is useful for transporting a DataStore file when you do not want to transfer the associated log files. If the DataStore has its txManager property set back to a TxManager that is enabled, it will become transactional again.
Note that transaction support cannot be disabled for a DataStore when the DataStore.consistent property is false. In this case it is best to copy the contents of the DataStore to a new DataStore by using the DataStore Explorer or the DataStoreConnection.copyStreams method.
public final int getLogBlockSize() public final void setLogBlockSize(int logBlockSize)Block size in increments of 1024 bytes to use for reading, writing, and caching of log file data.
public int getMaxLogSize() public synchronized void setMaxLogSize(int maxLogSize)When a log file fills up to this size, a new log file (with the next number) is created and used. For example, after
MyStore_LOGA_0000000000
reaches this size,
MyStore_LOGA_0000000001
is created to record further
transactions.
public int getMaxOpenLogs() public synchronized void setMaxOpenLogs(int maxOpenLogs)Maximum number of log files that will be kept open at one time. Higher values may improve performance, but they will consume more system file handles.
public final boolean isRecordStatus() public final synchronized void setRecordStatus(boolean recordStatus)Controls whether various status messages will be recorded to the
STATUS
log files, which are stored in the "A" log
directory.
public boolean isSoftCommit() public synchronized void setSoftCommit(boolean softCommit)Enables soft recovery.
When this property is set to true, crash recovery is still guaranteed, but the durability of the most recent commited transactions are not. Transactions commited within a second should be durable. Forcing (sync to disk) of the log file is performed for crash recovery purposes, but not to guarantee a transaction commit.
With softCommit set to false (the default) durability of transactions is guaranteed.
Setting this property improves performance, but can lead to recently commited transactions being rolled back after a system crash.