How to use Berkeley DB Java Edition

在学习爬虫的过程中，使用到了Berkeley DB。入门的使用方法，简洁有用。

——————————————————————————————————————————————————————————————————————

Our previous post “Introduction to Berkeley DB” gave an overview of the features and functionality of this popular DBMS. This post will show practical examples of the usage of Berkeley DB Java Edition in a Java application.

Versions of Berkeley DB for Java

There are two different versions of the Java API for Berkeley DB

Berkeley DB standard

The com.sleepycat.db package is an interface to the same system library used by other languages such as C, Perl and PHP to access BDB databases. This ensures the compatibility, allowing the use in a java application of a database created by an application written in other language.

Berkeley DB Java Edition

The com.sleepycat.je package is a 100% Java package. Databases created with this package can be moved to different platforms to be used by other java applications using the same library.

This post explains how to use Berkeley DB Java Edition.

Installation of Berkeley DB Java Edition

To install Berkeley DB Java edition, navigate in a browser to the Berkeley DB downloads page:

 http://www.oracle.com/technetwork/database/berkeleydb/downloads/index.html

From that page, download the file Berkeley DB Java Edition 5.0.58.tar.gz (13M)

To install, just uncompress and extract the files in a directory.

Note: If you chose to download the zip-compressed version of the file, use the -U option to preserve the capitalization of the file names.

Once installed, the file je-5.0.58/lib/je-5.0.58.jar must be added to the classpath to compile an run a java application that uses it.

In the directory je-5.0.58/lib  there are also other versions of the library, including one for the Android platform:

je-5.0.58 /lib $ ls -l
total 4952
-r--r--r-- 1 openalfa openalfa 2471774 Jul 17  2012 je-5.0.58.jar
-r--r--r-- 1 openalfa openalfa 2441012 Jul 17  2012 je-android-5.0.58.jar
-r--r--r-- 1 openalfa openalfa   55078 Jul 17  2012 JEJConsole.jar
-r--r--r-- 1 openalfa openalfa   79494 Jul 17  2012 RepJEJConsole.jar

Creating, opening and closing a database

The following code can be used to open a database, or create a new database:

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

import java.io.File;

public class TestBDB {

    public static void main(String[] args) {
        Environment myDbEnvironment = null ;
        Database myDatabase = null ;

        try {
            // Open the environment, creating one if it does not exist
            EnvironmentConfig envConfig = new EnvironmentConfig();
            envConfig.setAllowCreate( true );
            myDbEnvironment = new Environment( new File( "/tmp/dbEnv" ),
                                              envConfig);

            // Open the database, creating one if it does not exist
            DatabaseConfig dbConfig = new DatabaseConfig();
            dbConfig.setAllowCreate( true );
            myDatabase = myDbEnvironment.openDatabase( null ,
                                             "TestDatabase" , dbConfig);
        } catch (DatabaseException dbe) {
            //  Exception handling
        }
    }
}

In Berkeley DB Java Edition, an object of class Environment is mandatory to work with a BDB database. The first step in opening the database is creating this Environment object will a call to “new Environment”. The first argument to this call is the path where the data of the environment (including the databases in it) is located. The second argument is an object of class “EnvironmentConfig”. The call to “envConfig.setAllowCreate(true)” tells the constructor of the Environment object to create the required files if the environment did not previously exist.

Next, the database is opened with a call to “Environment.openDatabase”. This method receives as arguments the name of the database to be opened, and an object of class “DatabaseConfig”. In the same way as with the creation of the environment, a call to setAllowCreate(true) in the database configuration tells the constructor to create a new database if it did not exist.

When the application finishes making use of them, both the database and the environment must be closed like this:

try {
        if (myDatabase != null ) {
            myDatabase.close();
        }

        if (myDbEnvironment != null ) {
            myDbEnvironment.close();
        }
} catch (DatabaseException dbe) {
    // Exception handling
}

The example program “TestBDB.java” is compiled and executed with the commands:

$ javac -classpath je-5.0.58 /lib/je-5 .0.58.jar TestBDB.java
$ java -classpath .:je-5.0.58 /lib/je-5 .0.58.jar TestBDB

Writing records to the database

A record is written to the database with a call to the “put()” method of the Database object. This method receives as arguments two objects of the class DatabaseEntry, holding the key and the value of the record.

import com.sleepycat.je.Database;
import com.sleepycat.je.DatabaseEntry;

...

String key = "myKey" ;
String data = "myData" ;

try {
    DatabaseEntry theKey = new DatabaseEntry(key.getBytes( "UTF-8" ));
    DatabaseEntry theData = new DatabaseEntry(data.getBytes( "UTF-8" ));
    myDatabase.put( null , theKey, theData);
} catch (Exception e) {
    // Exception handling
}

Reading records from the database

The “get()” method in class Database can be used to retrieve a record. This method returns an object of class DataEntry, that must be converted to the desired object type.

import com.sleepycat.je.Database;
import com.sleepycat.je.DatabaseEntry;
import com.sleepycat.je.LockMode;
import com.sleepycat.je.OperationStatus;

...

String key = "myKey" ;

try {
    // Create two DatabaseEntry instances:
    // theKey is used to perform the search
    // theData will hold the value associated to the key, if found
    DatabaseEntry theKey = new DatabaseEntry(key.getBytes( "UTF-8" ));
    DatabaseEntry theData = new DatabaseEntry();

    // Call get() to query the database
    if (myDatabase.get(null, theKey, theData, LockMode.DEFAULT) ==
        OperationStatus.SUCCESS) {

        // Translate theData into a String.
        byte[] retData = theData.getData();
        String foundData = new String(retData, "UTF-8" );
        System .out.println( "key: '" + key + "' data: '" +
                            foundData + "'." );
    } else {
        System .out.println( "No record found with key '" + key + "'." );
    }
} catch (Exception e) {
    // Exception handling
}

Deleting records

The “delete” method in the Database class is used to delete a record from the database:

try {
    String key = "myKey" ;
    DatabaseEntry theKey = new DatabaseEntry(key.getBytes( "UTF-8" ));

    // Delete the entry (or entries) with the given key
    myDatabase.delete( null , theKey);
} catch (Exception e) {
    // Exception handling
}

Process all records in the database

The database can be traversed with the help of a cursor:

import com.sleepycat.je.Cursor;

Cursor myCursor = null ;

try {
    myCursor = myDatabase.openCursor( null , null );

    // Cursors returns records as pairs of DatabaseEntry objects
    DatabaseEntry foundKey = new DatabaseEntry();
    DatabaseEntry foundData = new DatabaseEntry();

    // Retrieve records with calls to getNext() until the
    // return status is not OperationStatus.SUCCESS
    while (myCursor.getNext(foundKey, foundData, LockMode.DEFAULT) ==
        OperationStatus.SUCCESS) {
        String keyString = new String(foundKey.getData(), "UTF-8" );
        String dataString = new String(foundData.getData(), "UTF-8" );
        System.out.println( "Key| Data : " + keyString + " | " +
                       dataString + "" );
    }
} catch (DatabaseException de) {
    System.err.println( "Error reading from database: " + de);
} finally {
    try {
        if (myCursor != null ) {
            myCursor.close();
        }
    } catch (DatabaseException dbe) {
        System.err.println( "Error closing cursor: " + dbe.toString());
    }
}