com.sun.sgs.impl.service.data.store.db.je
Class JeEnvironment

java.lang.Object
  com.sun.sgs.impl.service.data.store.db.je.JeEnvironment

All Implemented Interfaces:

DbEnvironment

public class JeEnvironment
extends Object
implements DbEnvironment

Provides a database implementation based on Berkeley DB Java Edition.

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 the following configuration properties:

Property: "com.sun.sgs.impl.service.data.store.db.je.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.je.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. Since Berkeley DB Java edition only detects deadlocks on lock timeouts, this value is also the amount of time it will take to detect a deadlock. The value must be greater than 0, and should be less than the transaction timeout.

Property: "com.sun.sgs.impl.service.data.store.db.je.stats"
Default: -1

The interval in milliseconds between calls to log database statistics, or a negative value to disable logging. The property is set to -1 by default, which disables statistics logging.

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

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

The constructor also supports any initialization properties supported by the Berkeley DB Environment class that start with the je. prefix.

Unless overridden, this implementation provides the following non-default settings for Berkeley DB initialization properties:

Property: je.checkpointer.bytesInterval
Value: 1000000

Perform checkpoints after 1 MB of changes. This setting improves performance when there are a large number of changes being committed.

Property: je.env.sharedLatches
Value: true

Use shared latches to improve concurrency.

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

• SEVERE - Berkeley DB failures that require application restart and recovery
• WARNING - Berkeley DB exceptions
• INFO - Berkeley DB statistics
• CONFIG - Constructor properties

Nested Class Summary

static class

JeEnvironment.TxnIsolationLevel The supported transaction isolation levels.

Field Summary

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 String	STATS_PROPERTY The property that specifies the interval in milliseconds between calls to log database statistics, or a negative value to disable logging.
static String	TXN_ISOLATION_PROPERTY The property that specifies the default transaction isolation level.

Constructor Summary

JeEnvironment(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(Exception e, boolean convertTxnExceptions) Returns the correct exception for a Berkeley DB DatabaseException, or XAException, 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.

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.

STATS_PROPERTY

public static final String STATS_PROPERTY

The property that specifies the interval in milliseconds between calls to log database statistics, or a negative value to disable logging. The property is set to -1 by default.

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

JeEnvironment

public JeEnvironment(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(Exception e,
                                         boolean convertTxnExceptions)

Returns the correct exception for a Berkeley DB DatabaseException, or XAException, 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 true to specify that this environment requires the use of allocation block placeholders.

Specified by:

useAllocationBlockPlaceholders in interface DbEnvironment

Returns:

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