com.sun.sgs.impl.service.data.store.db.bdb
Class BdbEnvironment

java.lang.Object
  com.sun.sgs.impl.service.data.store.db.bdb.BdbEnvironment

All Implemented Interfaces:

DbEnvironment

public class BdbEnvironment
extends Object
implements DbEnvironment

Provides a database implementation based on Berkeley DB.

Operations on classes in this package will throw an Error if the underlying Berkeley DB database requires recovery. In that case, callers need to restart the application or create a new instance of this class.

Note that, although databases returned by this class provide support for the DbTransaction.prepare method, they do not provide facilities for resolving prepared transactions after a crash. Callers can work around this limitation by insuring that the transaction implementation calls TransactionParticipant.prepareAndCommit to commit transactions on this class. The current transaction implementation calls prepareAndCommit on durable participants, so the inability to resolve prepared transactions should have no effect at present.

The constructor supports these public properties and the following additional properties:

Property: "com.sun.sgs.impl.service.data.store.db.bdb.checkpoint.interval"
Default: 60000L

The interval in milliseconds between checkpoint operations that flush changes from the database log to the database.

Property: "com.sun.sgs.impl.service.data.store.db.bdb.checkpoint.size"
Default: 100000L

The number of bytes that needs to have been written since the last checkpoint operation was performed to require another checkpoint.

Property: "com.sun.sgs.impl.service.data.store.db.bdb.flush.to.disk"
Default: false

Whether to flush changes to disk when a transaction commits. If false, the modifications made in some of the most recent transactions may be lost if the host crashes, although data integrity will be maintained. Flushing changes to disk avoids data loss but introduces a significant reduction in performance.

Property: "com.sun.sgs.impl.service.data.store.db.bdb.lock.timeout"
Default: 0.1 times the value of the com.sun.sgs.txn.timeout property, if specified, otherwise times the value of the default transaction timeout.

The maximum amount of time in milliseconds that an attempt to obtain a lock will be allowed to continue before being aborted. The value must be greater than 0, and should be less than the transaction timeout.

Property: "com.sun.sgs.impl.service.data.store.db.bdb.txn.isolation"
Default: SERIALIZABLE

The transaction isolation level, which should be one of READ_UNCOMMITTED, READ_COMMITTED, or SERIALIZABLE.

This class uses the Logger named com.sun.sgs.impl.service.data.db.bdb to log information at the following logging levels:

• SEVERE - Berkeley DB failures that require application restart and recovery
• WARNING - Berkeley DB errors
• CONFIG - Constructor properties
• FINE - Berkeley DB messages

Nested Class Summary

static class

BdbEnvironment.TxnIsolationLevel The supported transaction isolation levels.

Field Summary

static String	CACHE_SIZE_PROPERTY The property that specifies the size in bytes of the Berkeley DB cache.
static String	CHECKPOINT_INTERVAL_PROPERTY The property that specifies the time in milliseconds between checkpoints.
static String	CHECKPOINT_SIZE_PROPERTY The property that specifies how many bytes need to be modified before performing a checkpoint.
static long	DEFAULT_CACHE_SIZE The default cache size.
static long	DEFAULT_CHECKPOINT_INTERVAL The default checkpoint interval.
static long	DEFAULT_CHECKPOINT_SIZE The default checkpoint size.
static long	DEFAULT_LOCK_TIMEOUT The default value of the lock timeout property, if no transaction timeout is specified.
static double	DEFAULT_LOCK_TIMEOUT_PROPORTION The default proportion of the transaction timeout to use for the lock timeout, if no lock timeout is specified.
static String	FLUSH_TO_DISK_PROPERTY The property that specifies whether to flush changes to disk on transaction boundaries.
static String	LOCK_TIMEOUT_PROPERTY The property that specifies the amount of time permitted to obtain a lock, in milliseconds.
(package private) static LoggerWrapper	logger The logger for this class.
static long	MIN_CACHE_SIZE The minimum cache size, as specified by Berkeley DB.
static String	REMOVE_LOGS_PROPERTY The property that specifies whether to automatically remove log files.
static String	TXN_ISOLATION_PROPERTY The property that specifies the default transaction isolation level.

Constructor Summary

BdbEnvironment(String directory, Properties properties, ComponentRegistry systemRegistry, TransactionProxy txnProxy)
Creates an instance of this class.

Method Summary

DbTransaction	beginTransaction(long timeout) Begins a new transaction with the specified timeout and the implementation-specific default isolation level.
DbTransaction	beginTransaction(long timeout, boolean fullIsolation) Begins a transaction with the specified timeout and isolation level.
void	close() Closes the environment, releasing any associated resources.
(package private) static RuntimeException	convertException(com.sleepycat.db.DatabaseException e, boolean convertTxnExceptions) Returns the correct exception for a Berkeley DB DatabaseException thrown during an operation.
DbDatabase	openDatabase(DbTransaction txn, String fileName, boolean create) Opens a database.
boolean	useAllocationBlockPlaceholders() Specifies whether object allocations in this environment should use a placeholder at the end of each allocation block to avoid allocation concurrency conflicts.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

static final LoggerWrapper logger

The logger for this class.

CACHE_SIZE_PROPERTY

public static final String CACHE_SIZE_PROPERTY

The property that specifies the size in bytes of the Berkeley DB cache.

See Also:

Constant Field Values

MIN_CACHE_SIZE

public static final long MIN_CACHE_SIZE

The minimum cache size, as specified by Berkeley DB.

See Also:

Constant Field Values

DEFAULT_CACHE_SIZE

public static final long DEFAULT_CACHE_SIZE

The default cache size.

See Also:

Constant Field Values

CHECKPOINT_INTERVAL_PROPERTY

public static final String CHECKPOINT_INTERVAL_PROPERTY

The property that specifies the time in milliseconds between checkpoints.

See Also:

Constant Field Values

DEFAULT_CHECKPOINT_INTERVAL

public static final long DEFAULT_CHECKPOINT_INTERVAL

The default checkpoint interval.

See Also:

Constant Field Values

CHECKPOINT_SIZE_PROPERTY

public static final String CHECKPOINT_SIZE_PROPERTY

The property that specifies how many bytes need to be modified before performing a checkpoint.

See Also:

Constant Field Values

DEFAULT_CHECKPOINT_SIZE

public static final long DEFAULT_CHECKPOINT_SIZE

The default checkpoint size.

See Also:

Constant Field Values

FLUSH_TO_DISK_PROPERTY

public static final String FLUSH_TO_DISK_PROPERTY

The property that specifies whether to flush changes to disk on transaction boundaries. The property is set to false by default. If false, some recent transactions may be lost in the event of a crash, although integrity will be maintained.

See Also:

Constant Field Values

LOCK_TIMEOUT_PROPERTY

public static final String LOCK_TIMEOUT_PROPERTY

The property that specifies the amount of time permitted to obtain a lock, in milliseconds.

See Also:

Constant Field Values

DEFAULT_LOCK_TIMEOUT_PROPORTION

public static final double DEFAULT_LOCK_TIMEOUT_PROPORTION

The default proportion of the transaction timeout to use for the lock timeout, if no lock timeout is specified.

See Also:

Constant Field Values

DEFAULT_LOCK_TIMEOUT

public static final long DEFAULT_LOCK_TIMEOUT

The default value of the lock timeout property, if no transaction timeout is specified.

REMOVE_LOGS_PROPERTY

public static final String REMOVE_LOGS_PROPERTY

The property that specifies whether to automatically remove log files.

See Also:

Constant Field Values

TXN_ISOLATION_PROPERTY

public static final String TXN_ISOLATION_PROPERTY

The property that specifies the default transaction isolation level.

See Also:

Constant Field Values

Constructor Detail

BdbEnvironment

public BdbEnvironment(String directory,
                      Properties properties,
                      ComponentRegistry systemRegistry,
                      TransactionProxy txnProxy)

Creates an instance of this class.

Parameters:

directory - the directory containing database files

properties - the properties to configure this instance

systemRegistry - the registry of available system components

txnProxy - the transaction proxy

Throws:

DbDatabaseException - if an unexpected database problem occurs

Method Detail

convertException

static RuntimeException convertException(com.sleepycat.db.DatabaseException e,
                                         boolean convertTxnExceptions)

Returns the correct exception for a Berkeley DB DatabaseException thrown during an operation. Throws an Error if recovery is needed. Only converts Berkeley DB transaction exceptions to the associated exceptions if convertTxnExceptions is true.

beginTransaction

public DbTransaction beginTransaction(long timeout)

Begins a new transaction with the specified timeout and the implementation-specific default isolation level.

Specified by:

beginTransaction in interface DbEnvironment

Parameters:

timeout - the number of milliseconds the transaction should be allowed to run

Returns:

the transaction

beginTransaction

public DbTransaction beginTransaction(long timeout,
                                      boolean fullIsolation)

Begins a transaction with the specified timeout and isolation level.

Specified by:

beginTransaction in interface DbEnvironment

Parameters:

timeout - the number of milliseconds the transaction should be allowed to run

fullIsolation - if true, requires the transaction to support full serializable isolation, otherwise uses the default transaction isolation level

Returns:

the transaction

openDatabase

public DbDatabase openDatabase(DbTransaction txn,
                               String fileName,
                               boolean create)
                        throws FileNotFoundException

Opens a database. Relative database filenames will be interpreted relative to whatever root directory was specified when this environment was created, typically the directory argument passed to DbEnvironmentFactory.getEnvironment.

Specified by:

openDatabase in interface DbEnvironment

Parameters:

txn - the transaction under which the database should be opened

fileName - the name of the file containing the database

create - whether to create the database if it does not exist

Returns:

the database

Throws:

FileNotFoundException - if create is false and the database is not found

close

public void close()

Closes the environment, releasing any associated resources. This environment should not be used after this method is called. This method should not be called if any of the transactions or databases associated with this environment are still open.

Specified by:

close in interface DbEnvironment

useAllocationBlockPlaceholders

public boolean useAllocationBlockPlaceholders()

Specifies whether object allocations in this environment should use a placeholder at the end of each allocation block to avoid allocation concurrency conflicts.

This implementation returns false to specify that this environment does not require the use of allocation block placeholders.

Specified by:

useAllocationBlockPlaceholders in interface DbEnvironment

Returns:

whether object allocations should use an end-of-block placeholder