Table of Contents
Berkeley DB Java Edition requires that all databases be placed in an database environment. Database environments encapsulate one or more databases. This encapsulation provides your threads with efficient access to your databases by allowing a single in-memory cache to be used for each of the databases contained in the environment. This encapsulation also allows you to group operations performed against multiple databases inside a single transactions (see Transactions for more information).
Most commonly you use database environments to create and open databases (you close individual databases using the individual database handles). You can also use environments to delete and rename databases. For transactional applications, you use the environment to start transactions. For non-transactional applications, you use the environment to sync your in-memory cache to disk.
You can also use the database environment for administrative and configuration activities related to your database log files and the in-memory cache. See Administering Berkeley DB Java Edition Applications for more information.
For information on managing databases using database environments, see Databases. To find out how to use environments with a transactionally protected application, see Transactions.
You open a database environment by instantiating an Environment object. You must provide to the constructor the name of the on-disk directory where the environment is to reside. This directory location must exist or the open will fail.
By default, JE will not create the environment for you if it does not exist. Set the creation property to true if you want JE to create the environment. For example:
import com.sleepycat.je.Environment;
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.EnvironmentConfig;
import java.io.File;
...
// Open the environment. Allow it to be created if it does not already exist.
Environment myDbEnvironment;
try {
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setAllowCreate(true);
myDbEnvironment = new Environment(new File("/export/dbEnv"), envConfig);
} catch (DatabaseException dbe) {
// Exception handling goes here
}
Your application can open and use as many environments as you have disk and memory to manage, although most applications will use just one environment. Also, you can instantiate multiple Environment objects for the same physical environment.
Note that opening an environment usually causes some background threads to be started. JE uses these threads for log file cleaning and some in-memory cache administrative tasks. However, these threads will only be opened once per process, so if you open the same environment more than once from within the same process, there is no performance impact on your application. Also, if you open the environment as read-only, then the background threads (with the exception of the evictor thread) are not started.
Also, opening your environment causes normal recovery to be run. This causes your databases to be brought into a consistent state relative to the changed data found in your log files. See Databases and Log Files for more information.