Berkeley DB Reference Guide: Opening and closing the database stores

Berkeley DB Reference Guide:
Java API Tutorial - Basic

Opening and closing the database stores

This section describes how to open and close the Part, Supplier and Shipment stores. A Java API store is a collection of records, each of which has a key and a value. The keys and values are assigned a format, which defines the syntax of the stored data. Two examples of formats are Java serialization format and tuple format. In a given store, all keys have the same format and all values have the same format.

Two central classes in the Berkeley DB and Java API are introduced here: Db and DataStore . Both are needed to create a store in the Java API. The differences between the two classes are:

The Db class is part of the com.sleepycat.db package, while the DataStore class is part of the com.sleepycat.bdb package.
A DataStore object is a wrapper around the Db object, and adds functionality to it. For every DataStore object there is a single Db object underlying it.
Keys and values in a Db are always treated as byte arrays, while keys and values in a DataStore have a defined format.
A Db is used to represent a primary store or a secondary index, while a DataStore always represents a primary store. Secondary indices are introduced in the Index program tutorial.

The SampleDatabase class is extended to open and close the three stores. The following additional imports and class members are needed.

import com.sleepycat.bdb.bind.serial.SerialFormat;
import com.sleepycat.bdb.DataStore;
...
public class SampleDatabase
{
    ...
    private static final String SUPPLIER_STORE = "supplier_store";
    private static final String PART_STORE = "part_store";
    private static final String SHIPMENT_STORE = "shipment_store";
    ...
    private DataStore supplierStore;
    private DataStore partStore;
    private DataStore shipmentStore;
    private SerialFormat partKeyFormat;
    private SerialFormat partValueFormat;
    private SerialFormat supplierKeyFormat;
    private SerialFormat supplierValueFormat;
    private SerialFormat shipmentKeyFormat;
    private SerialFormat shipmentValueFormat;
    ...
}

For each store there is a filename constant and a DataStore object. A SerialFormat object represents the Java serialization format for the key and value of each store.

The following statements create the format objects.

    public SampleDatabase(String homeDirectory, boolean runRecovery)
        throws DbException, FileNotFoundException
    {
        ...
        partKeyFormat = new SerialFormat(javaCatalog, PartKey.class);
        partValueFormat = new SerialFormat(javaCatalog, PartValue.class);
        supplierKeyFormat = new SerialFormat(javaCatalog, SupplierKey.class);
        supplierValueFormat = new SerialFormat(javaCatalog, SupplierValue.class);
        shipmentKeyFormat = new SerialFormat(javaCatalog, ShipmentKey.class);
        shipmentValueFormat = new SerialFormat(javaCatalog, ShipmentValue.class);
    }

The first parameter of the SerialFormat constructor is the class catalog, and is used to store the class descriptions of the serialized objects.

The second parameter is the base class for the serialized objects and is used for type checking of the stored objects. If null or Object.class is specified, then any Java class is allowed. Otherwise, all objects stored in that format must be instances of the specified class or derived from the specified class. In the example, specific classes are used to enable strong type checking.

The following statements open the three stores using the Db and DataStore classes. The files are created if they don't already exist. For each store, a Db object is created, its Db.open method is called, and then a DataStore object is created.

    public SampleDatabase(String homeDirectory, boolean runRecovery)
        throws DbException, FileNotFoundException
    {
        ...
        int flags = Db.DB_CREATE | Db.DB_AUTO_COMMIT;
        ...
        Db partDb = new Db(env, 0);
        partDb.open(null, PART_STORE, null, Db.DB_BTREE, flags, 0);
        partStore = new DataStore(partDb, partKeyFormat, partValueFormat, null);

        Db supplierDb = new Db(env, 0);
        supplierDb.open(null, SUPPLIER_STORE, null, Db.DB_BTREE, flags, 0);
        supplierStore = new DataStore(supplierDb, supplierKeyFormat, supplierValueFormat, null);

        Db shipmentDb = new Db(env, 0);
        shipmentDb.open(null, SHIPMENT_STORE, null, Db.DB_BTREE, flags, 0);
        shipmentStore = new DataStore(shipmentDb, shipmentKeyFormat, shipmentValueFormat, null);
    }

The first parameter of the Db constructor is the environment in which the store will operate. The second parameter contains flags and is not used in the example.

The first parameter of the Db.open method is a transaction object. It is null in the example because the Db.DB_AUTO_COMMIT flag is used to create the store within an implicit transaction.

NOTE: An important point to remember is that either the Db.DB_AUTO_COMMIT flag or the transaction parameter must be specified in order to open a transactional store.

The second and third String parameters specify the filename and database (sub-file) name of the store. The database (sub-file) name is optional, and is null in the example.

The fourth parameter is the store's type, and determines which of the database Access Methods is used. In general, the store's type determines the characteristics of its keys. The Db.DB_BTREE type provides ordered keys and optimal performance for most applications. The Db.DB_HASH type can provide better performance for very large database, but does not provide ordered keys. Although DB_BTREE is used here, the ordering of keys is not meaningful because the key values are serialized Java objects. In a later example the tuple format will be used to provide a meaningful key ordering. Other types are Db.DB_QUEUE and Db.DB_RECNO . A store's type cannot be changed once the store has been created.

The fifth parameter contains flags and is initialized with Db.DB_CREATE to create the file if it doesn't exist and with Db.DB_AUTO_COMMIT (described previously).

The last parameter is the UNIX file creation mode. Zero is specified in the example to use a reasonable default.

Finally, the DataStore object is created from the Db object, a key format, and a value format. The last parameter of the DataStore constructor is a primary key assigner, and is not used in the example.

The following statements close the three stores.

    public void close()
        throws DbException, IOException
    {
        partStore.close();
        supplierStore.close();
        shipmentStore.close();
        javaCatalog.close();
        env.close(0);
    }

All stores, including the catalog store, must be closed before closing the environment.

The following getter methods return the formats and stores for use by other classes in the example program. The formats are used for creating bindings, and the stores are used for creating Java collections.

public class SampleDatabase
{
    ...
    public final SerialFormat getPartKeyFormat()
    {
        return partKeyFormat;
    }

    public final SerialFormat getPartValueFormat()
    {
        return partValueFormat;
    }

    public final SerialFormat getSupplierKeyFormat()
    {
        return supplierKeyFormat;
    }

    public final SerialFormat getSupplierValueFormat()
    {
        return supplierValueFormat;
    }

    public final SerialFormat getShipmentKeyFormat()
    {
        return shipmentKeyFormat;
    }

    public final SerialFormat getShipmentValueFormat()
    {
        return shipmentValueFormat;
    }

    public final DataStore getPartStore()
    {
        return partStore;
    }

    public final DataStore getSupplierStore()
    {
        return supplierStore;
    }

    public final DataStore getShipmentStore()
    {
        return shipmentStore;
    }
    ...
}

Berkeley DB Reference Guide:Java API Tutorial - Basic

Opening and closing the database stores

Berkeley DB Reference Guide:
Java API Tutorial - Basic