Table of Contents
In Berkeley DB Java Edition, a database is a collection of records. Records, in turn, consist of two database entries, one of which is a key and one of which is data. That is, records consist of key/data pairs of database entries.
Conceptually, you can think of a Database as containing a two-column table where column 1 contains a key and column 2 contains data. Both the key and the data are managed using DatabaseEntry class instances (see Database Records for details on this class ). So, fundamentally, using a JE Database involves putting, getting, deleting, and sorting database records, which in turns involves efficiently managing information encapsulated by DatabaseEntry objects. The next several chapters of this book are dedicated to those activities.
Note that on disk, databases are stored in log files in the directory where the opening environment is located. JE log files are described Databases and Log Files.
You open a database by using the Environment.openDatabase() method (environments are described in Database Environments). This method creates and returns a Database object handle to you. You must provide Environment.openDatabase() with a database name. This name is a Java String object that uniquely identifies the database.
You can optionally provide Environment.openDatabase() with a DatabaseConfig() object. DatabaseConfig() allows you to set properties for the database, such as whether it can be created if it does not currently exist, whether you are opening it read-only, and whether the database is to support transactions.
Note that by default, JE does not create databases if they do not already exist. To override this behavior, set the creation property to true.
Finally, if you configured your environment and database to support transactions, you can optionally provide a transaction object to the Environment.openDatabase(). Transactions are described in Transactions later in this manual.
The following code fragment illustrates a database open:
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.Database;
import com.sleepycat.je.DatabaseConfig;
import com.sleepycat.je.Environment;
import com.sleepycat.je.EnvironmentConfig;
import java.io.File;
...
Environment myDbEnvironment;
Database myDatabase;
...
try {
// Open the environment. Create it if it does not already exist.
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setAllowCreate(true);
myDbEnvironment = new Environment(new File("/export/dbEnv"), envConfig);
// Open the database. Create it if it does not already exist.
DatabaseConfig dbConfig = new DatabaseConfig();
dbConfig.setAllowCreate(true);
myDatabase = myDbEnvironment.openDatabase(null,
"sampleDatabase",
dbConfig);
} catch (DatabaseException dbe) {
// Exception handling goes here
}
Once you are done using the database, you must close it. You use the Database.close() method to do this.
Closing a database causes it to become unusable until it is opened again. If any cursors are opened for the database, JE warns you about the open cursors, and then closes them for you. Active cursors during a database close can cause unexpected results, especially if any of those cursors are writing to the database. You should always make sure that all your database accesses have completed before closing your database.
Remember that for the same reason, you should always close all your databases before closing the environment to which they belong.
Cursors are described in Using Cursors later in this manual.
The following illustrates a database close:
import com.sleepycat.je.DatabaseException;
import com.sleepycat.je.Database;
import com.sleepycat.je.Environment;
...
try {
if (myDatabase != null) {
myDatabase.close();
}
if (myDbEnvironment != null) {
myDbEnvironment.close();
}
} catch (DatabaseException dbe) {
// Exception handling goes here
}