Database Environment Example

This example provides a complete class that can open and close an environment. It is both extended and used in subsequent examples in this book to open and close both environments and databases. We do this so as to make the example code shorter and easier to manage. You can find this class in:

JE_HOME/examples/com/sleepycat/examples/je/gettingStarted/examples/
MyDbEnv.java

where JE_HOME is the location where you placed your JE distribution.

Example 2.1 Database Environment Management Class

First we write the normal class declarations. We also set up some private data members that are used to manage environment creation. We use the class constructor to instantiate the EnvironmentConfig object that is used to configure our environment when we open it.

// File MyDbEnv.java

package com.sleepycat.examples.je.gettingStarted;

import java.io.File;

import com.sleepycat.je.EnvironmentConfig;
import com.sleepycat.je.Environment;
import com.sleepycat.je.DatabaseException;


public class MyDbEnv {

    private Environment myEnv;

    public MyDbEnv() {} 

Next we need a method to open the environment. This is responsible for instantiating our Environment object. Remember that instantiation is what opens the environment (or creates it if the creation property is set to true and the environment does not currently exist).

    public void setup(File envHome, boolean readOnly) 
            throws DatabaseException {

        // Instantiate an environment configuration object
        EnvironmentConfig myEnvConfig = new EnvironmentConfig();
        // Configure the environment for the read-only state as identified by
        // the readOnly parameter on this method call.
        myEnvConfig.setReadOnly(readOnly);
        // If the environment is opened for write, then we want to be able to
        // create the environment if it does not exist.
        myEnvConfig.setAllowCreate(!readOnly);

        // Instantiate the Environment. This opens it and also possibly
        // creates it.
        myEnv = new Environment(envHome, myEnvConfig);
    } 

Next we provide a getter method that allows us to retrieve the Environment directly. This is needed for later examples in this guide.

    // Getter methods
    public Environment getEnv() {
        return myEnv;
    } 

Finally, we need a method to close our Environment. We wrap this operation in a try block so that it can be used gracefully in a finally statement.

    // Close the environment
    public void close() {
        if (myEnv != null) {
            try {
                myEnv.close();
            } catch(DatabaseException dbe) {
                System.err.println("Error closing environment" + 
                     dbe.toString());
            }
        }
    }
} 

This completes the MyDbEnv class. While not particularly useful as it currently exists, we will build upon it throughout this book so that it will eventually open and close all of the databases required by our applications.

We can now use MyDbEnv to open and close a database environment from the appropriate place in our application. For example:

package com.sleepycat.examples.je.gettingStarted;

import com.sleepycat.je.DatabaseEntry;
import java.io.File;

...

MyDbEnv exampleDbEnv = new MyDbEnv();

try {    
    exampleDbEnv.setup(new File("/directory/currently/exists"), true);
    ...

} catch(DatabaseException dbe) {
    // Error code goes here
} finally {
    exampleDbEnv.close();
}