Berkeley DB Reference Guide: Opening and closing the database environment

Berkeley DB Reference Guide:
Java API Tutorial - Basic

Opening and closing the database environment

This section of the tutorial describes how to open and close the database environment. The database environment manages resources (for example, memory) and transactions for any number of database stores. A single environment instance is normally used for all stores, although some advanced applications may use multiple environments.

The SampleDatabase class is used to open and close the database environment. It will also be used in following sections to open and close the class catalog and database stores. Its constructor is used to open the database and its close() method is used to close the database. The skeleton for the SampleDatabase class follows.

import com.sleepycat.db.Db;
import com.sleepycat.db.DbException;
import com.sleepycat.db.DbEnv;
import java.io.FileNotFoundException;
import java.io.IOException;

public class SampleDatabase
{
    private DbEnv env;

    public SampleDatabase(String homeDirectory, boolean runRecovery)
        throws DbException, FileNotFoundException
    {
    }

    public void close()
        throws DbException, IOException
    {
    }
}

The first thing to notice is that the DbEnv class is in the com.sleepycat.db package, not the com.sleepycat.bdb package. The db package contains all core Berkeley DB functionality and is the same across all supported programming languages. The bdb package contains extended functionality that is Java-specific and based on the Java Collections API. The bdb package is layered on top of the db package. Both packages are needed to create a complete application based on the Java API.

The following statements create a DbEnv object and call its DbEnv.open method.

    public SampleDatabase(String homeDirectory, boolean runRecovery)
        throws DbException, FileNotFoundException
    {
        int envFlags = Db.DB_INIT_TXN | Db.DB_INIT_LOCK | Db.DB_INIT_MPOOL |
                       Db.DB_CREATE;
        if (runRecovery) envFlags |= Db.DB_RECOVER;
        env = new DbEnv(0);
        System.out.println("Opening environment in: " + homeDirectory);
        env.open(homeDirectory, envFlags, 0);
    }

Notice that flags are used to specify options for the environment when it is opened. Flags are used in many places in the Berkeley DB API. To specify more than one flag, OR them together with the '|' operator as shown.

The first three environment flags used -- Db.DB_INIT_TXN , Db.DB_INIT_LOCK , and Db.DB_INIT_MPOOL -- must always be specified when opening a transactional environment. While non-transactional environments can also be created, the examples in this tutorial use a transactional environment.

The Db.DB_CREATE flag specifies that the environment's files (database, log and shared memory pool files) will be created if they don't already exist. If this flag is not specified, an exception will be thrown if the environment does not already exist. The same flag will be used later to cause database stores to be created if they don't exist.

The Db.DB_RECOVER flag causes database recovery to be performed, if recovery is necessary because of an error that occurred previously. In general, it is safe to run recovery unconditionally if the current process is known to be the only one attempting to access the database. The runRecovery parameter in the example is used to control this behavior so that recovery can be coordinated among multiple processes. This will be explained further when the example's main() method is described.

When the DbEnv.open method is called, a home directory, a flags parameter, and a file open mode are specified. The home directory is the location of the environment files and is the default parent directory for database store files. The flags are those described above. The open mode is used for creating files on UNIX systems, where zero means to use a reasonable default.

The following statement closes the environment. The environment should always be closed when database work is completed to free allocated resources and to prevent having to run recovery later. Closing the environment does not automatically close database stores, so stores must be closed explicitly before closing the environment.

    public void close()
        throws DbException, IOException
    {
        env.close(0);
    }

The following getter method returns the environment for use by other classes in the example program. The environment is used for running transactions, among other things.

public class SampleDatabase
{
    ...
    public final DbEnv getEnvironment()
    {
        return env;
    }
    ...
}

Berkeley DB Reference Guide:Java API Tutorial - Basic

Opening and closing the database environment

Berkeley DB Reference Guide:
Java API Tutorial - Basic