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 * 12Default 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*128)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 recently committed transactions is not. The log file is still forced to disk for crash recovery purposes, but not every time a transaction is committed. Usually only transactions committed in the last second before a crash are lost.
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.