com.sleepycat.je
Class Environment

java.lang.Object
  |
  +--com.sleepycat.je.Environment

public class Environment

extends Object

A database environment.

To open an existing environment with default attributes the application may use a default environment configuration object or null:

// Open an environment handle with default attributes.
Environment env = new Environment(home, new EnvironmentConfig());

or

Environment env = new Environment(home, null);

Note that many Environment objects may access a single environment.

To create an environment or customize attributes, the application should customize the configuration class. For example:

EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setTransactional(true);
envConfig.setAllowCreate(true);
envConfig.setCacheSize(1000000);

Environment newlyCreatedEnv = new Environment(home, envConfig);

Note that environment configuration parameters can also be set through the <environment home>/je.properties file. This file takes precedence over any programmatically specified configuration parameters so that configuration changes can be made without recompiling. Environment configuration follows this order of precedence:

1. Configuration parameters specified in <environment home>/je.properties take first precedence.
2. Configuration parameters set in the EnvironmentConfig object used at Environment construction are next.
3. Any configuration parameters not set by the application are set to system defaults, described in the example.properties file included at the top of the distribution.

An environment handle is an Environment instance. More than one Environment instance may be created for the same physical directory, which is the same as saying that more than one Environment handle may be open at one time for a given environment.

The Environment handle should not be closed while any other handle remains open that is using it as a reference (for example, Database or Transaction. Once the Environment.close method is called, this object may not be accessed again, regardless of the method's return.

Constructor Summary

Environment(File envHome, EnvironmentConfig envConfig)
Create a database environment handle.

Method Summary

Transaction	beginTransaction(Transaction parent, TransactionConfig txnConfig) Create a new transaction in the database environment.
void	checkpoint(CheckpointConfig checkpointConfig) Synchronously checkpoint the database environment.
int	cleanLog() Synchronously invoke database environment log cleaning.
void	close() The Environment.close method closes the Berkeley DB environment.
void	compress() Synchronously invoke the compressor mechanism which compacts in memory data structures after delete operations.
void	evictMemory() Synchronously invoke the mechanism for keeping memory usage within the cache size boundaries.
EnvironmentConfig	getConfig() Return this object's configuration.
List	getDatabaseNames() Return a List of database names for the database environment.
File	getHome() Return the database environment's home directory.
LockStats	getLockStats(StatsConfig statsConfig) Return database environment locking statistics.
EnvironmentMutableConfig	getMutableConfig() Return database environment attributes.
EnvironmentStats	getStats(StatsConfig statsConfig) Return general database environment statistics.
TransactionStats	getTransactionStats(StatsConfig statsConfig) Return database environment transactional statistics.
Database	openDatabase(Transaction txn, String databaseName, DatabaseConfig dbConfig) Open, and optionally create, a Database.
SecondaryDatabase	openSecondaryDatabase(Transaction txn, String databaseName, Database primaryDatabase, SecondaryConfig secConfig) Open and optionally create a SecondaryDatabase.
void	removeDatabase(Transaction txn, String databaseName) Remove a database.
void	renameDatabase(Transaction txn, String databaseName, String newName) Rename a database.
void	setMutableConfig(EnvironmentMutableConfig envMutableConfig) Set database environment attributes.
void	sync() Synchronously flush database environment databases to stable storage.
boolean	verify(VerifyConfig verifyConfig, PrintStream out) Verify that the database environment is consistent and correct.

Methods inherited from class java.lang.Object

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

Constructor Detail

Environment

public Environment(File envHome,
                   EnvironmentConfig envConfig)
            throws DatabaseException

Create a database environment handle.

Parameters:

envHome - The database environment's home directory.

envConfig - The envConfig parameter specifies the database environment attributes; if null, default attributes are used.

Throws:

IllegalArgumentException - if an invalid parameter was specified.

DatabaseException - if a failure occurs.

Method Detail

close

public void close()
           throws DatabaseException

The Environment.close method closes the Berkeley DB environment.

When the last environment handle is closed, allocated resources are freed, and daemon threads are stopped.

The Environment handle should not be closed while any other handle that refers to it is not yet closed; for example, database environment handles must not be closed while database handles remain open, or transactions in the environment have not yet committed or aborted. Specifically, this includes Database, Cursor and Transaction handles.

In multithreaded applications, only a single thread may call Environment.close.

After Environment.close has been called, regardless of its return, the Berkeley DB environment handle may not be accessed again.

Throws:

DatabaseException - if a failure occurs.

openDatabase

public Database openDatabase(Transaction txn,
                             String databaseName,
                             DatabaseConfig dbConfig)
                      throws DatabaseException

Open, and optionally create, a Database.

Parameters:

txn - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified.

databaseName - The name of the database.

dbConfig - The dbConfig parameter specifies the database attributes; if null, default attributes are used.

Returns:

Database handle.

Throws:

DatabaseNotFoundException - if the database file does not exist.

DatabaseException - if a failure occurs.

openSecondaryDatabase

public SecondaryDatabase openSecondaryDatabase(Transaction txn,
                                               String databaseName,
                                               Database primaryDatabase,
                                               SecondaryConfig secConfig)
                                        throws DatabaseException

Open and optionally create a SecondaryDatabase.

Parameters:

txn - For a transactional database, an explicit transaction may be specified, or null may be specified to use auto-commit. For a non-transactional database, null must be specified.

databaseName - The name of the database.

primaryDatabase - the primary database with which the secondary database will be associated.

secConfig - The secConfig parameter specifies the secondary database attributes; if null, default attributes are used.

Returns:

Database handle.

Throws:

DatabaseNotFoundException - if the database file does not exist.

DatabaseException - if a failure occurs.

removeDatabase

public void removeDatabase(Transaction txn,
                           String databaseName)
                    throws DatabaseException

Remove a database.

Applications should never remove databases with open Database handles.

Parameters:

txn - For a transactional environment, an explicit transaction may be specified or null may be specified to use auto-commit. For a non-transactional environment, null must be specified.

databaseName - The database to be removed.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

DatabaseNotFoundException - if the database file does not exist.

DatabaseException - if a failure occurs.

renameDatabase

public void renameDatabase(Transaction txn,
                           String databaseName,
                           String newName)
                    throws DatabaseException

Rename a database.

Applications should never remove databases with open Database handles.

Parameters:

txn - For a transactional environment, an explicit transaction may be specified or null may be specified to use auto-commit. For a non-transactional environment, null must be specified.

databaseName - The new name of the database.

Throws:

DeadlockException - if the operation was selected to resolve a deadlock.

DatabaseNotFoundException - if the database file does not exist.

DatabaseException - if a failure occurs.

getHome

public File getHome()
             throws DatabaseException

Return the database environment's home directory.

Returns:

The database environment's home directory.

Throws:

DatabaseException - if a failure occurs.

beginTransaction

public Transaction beginTransaction(Transaction parent,
                                    TransactionConfig txnConfig)
                             throws DatabaseException

Create a new transaction in the database environment.

Transactions may span threads, however they will only perform work serially, that is, a transaction will be active in only a single thread of control at a time.

Cursors may not span transactions; that is, each cursor must be opened and closed within a single transaction.

Parameters:

parent - If the param parameter is non-null, the new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level.

txnConfig - The txnConfig parameter specifies the transaction attributes; if null, default attributes are used.

Returns:

The newly created transaction's handle.

Throws:

DatabaseException - if a failure occurs.

checkpoint

public void checkpoint(CheckpointConfig checkpointConfig)
                throws DatabaseException

Synchronously checkpoint the database environment.

This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.

Parameters:

checkpointConfig - The checkpointConfig parameter specifies the checkpoint attributes; if null, default attributes are used.

Throws:

DatabaseException - if a failure occurs.

sync

public void sync()
          throws DatabaseException

Synchronously flush database environment databases to stable storage.

Throws:

DatabaseException - if a failure occurs.

cleanLog

public int cleanLog()
             throws DatabaseException

Synchronously invoke database environment log cleaning. Zero or more log files will be cleaned as necessary to bring the disk space utilization of the environment above the configured minimum utilization threshold.

This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.

Returns:

the number of log files that were cleaned.

Throws:

DatabaseException - if a failure occurs.

evictMemory

public void evictMemory()
                 throws DatabaseException

Synchronously invoke the mechanism for keeping memory usage within the cache size boundaries.

This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.

Throws:

DatabaseException - if a failure occurs.

compress

public void compress()
              throws DatabaseException

Synchronously invoke the compressor mechanism which compacts in memory data structures after delete operations.

This is an optional action for the application since this activity is, by default, handled by a database environment owned background thread.

Throws:

DatabaseException - if a failure occurs.

getConfig

public EnvironmentConfig getConfig()
                            throws DatabaseException

Return this object's configuration.

Returns:

This object's configuration.

Throws:

DatabaseException - if a failure occurs.

setMutableConfig

public void setMutableConfig(EnvironmentMutableConfig envMutableConfig)
                      throws DatabaseException

Set database environment attributes.

Attributes only apply to a specific Environment object and are not necessarily shared by other Environment objects accessing this database environment.

Parameters:

envMutableConfig - The envMutableConfig parameter specifies the database environment attributes; if null, default attributes are used.

Throws:

DatabaseException - if a failure occurs.

getMutableConfig

public EnvironmentMutableConfig getMutableConfig()
                                          throws DatabaseException

Return database environment attributes.

Returns:

Environment attributes

Throws:

DatabaseException - if a failure occurs.

getStats

public EnvironmentStats getStats(StatsConfig statsConfig)
                          throws DatabaseException

Return general database environment statistics.

Parameters:

statsConfig - The statsConfig parameter specifies the general statistics attributes; if null, default attributes are used.

Returns:

General database environment statistics.

Throws:

DatabaseException - if a failure occurs.

getLockStats

public LockStats getLockStats(StatsConfig statsConfig)
                       throws DatabaseException

Return database environment locking statistics.

Parameters:

statsConfig - The statsConfig parameter specifies the locking statistics attributes; if null, default attributes are used.

Returns:

Database environment locking statistics.

Throws:

DatabaseException - if a failure occurs.

getTransactionStats

public TransactionStats getTransactionStats(StatsConfig statsConfig)
                                     throws DatabaseException

Return database environment transactional statistics.

Parameters:

statsConfig - The statsConfig parameter specifies the transactional statistics attributes; if null, default attributes are used.

Returns:

Database environment transactional statistics.

Throws:

DatabaseException - if a failure occurs.

getDatabaseNames

public List getDatabaseNames()
                      throws DatabaseException

Return a List of database names for the database environment.

Each element in the list is a String.

Returns:

A List of database names for the database environment.

Throws:

DatabaseException - if a failure occurs.

verify

public boolean verify(VerifyConfig verifyConfig,
                      PrintStream out)
               throws DatabaseException

Verify that the database environment is consistent and correct.

Parameters:

verifyConfig - The verifyConfig parameter specifies the verification attributes; if null, default attributes are used.

out - the stream to which verification debugging information is written.

Returns:

true if verification succeeded, false if there was a problem.

Throws:

DatabaseException - if a failure occurs.