The Direct Persistence Layer (DPL) adds a persistent object model to the Berkeley DB transactional engine.

Package Specification

Introduction

The Direct Persistence Layer (DPL) was designed to meet the following requirements.

The Entity Model

The DPL is intended for applications that represent persistent domain objects using Java classes. An entity class is an ordinary Java class that has a primary key and is stored and accessed using a primary index. It may also have any number of secondary keys, and entities may be accessed by secondary key using a secondary index.

An entity class may be defined with the {@link com.sleepycat.persist.model.Entity Entity} annotation. For each entity class, its primary key may be defined using the {@link com.sleepycat.persist.model.PrimaryKey PrimaryKey} annotation and any number of secondary keys may be defined using the {@link com.sleepycat.persist.model.SecondaryKey SecondaryKey} annotation.

In the following example, the {@code Person.ssn} (social security number) field is the primary key and the {@code Person.employerIds} field is a many-to-many secondary key.

{@literal @Entity}
class Person {

    {@literal @PrimaryKey}
    String ssn;

    String name;
    Address address;

    {@literal @SecondaryKey(relate=MANY_TO_MANY, relatedEntity=Employer.class)}
    {@literal Set employerIds = new HashSet();}

    private Person() {} // For bindings
}

A set of entity classes constitutes an entity model. In addition to isolated entity classes, an entity model may contain relationships between entities. Relationships may be defined using the {@link com.sleepycat.persist.model.SecondaryKey SecondaryKey} annotation. Many-to-one, one-to-many, many-to-many and one-to-one relationships are supported, as well as foreign key constraints.

In the example above, a relationship between the {@code Person} and {@code Employer} entities is defined via the {@code Person.employerIds} field. The {@code relatedEntity=Employer.class} annotation property establishes foreign key constraints to guarantee that every element of the {@code employerIds} set is a valid {@code Employer} primary key.

For more information on the entity model, see the {@link com.sleepycat.persist.model.AnnotationModel AnnotationModel} and the {@link com.sleepycat.persist.model.Entity Entity} annotation.

The root object in the DPL is the {@link com.sleepycat.persist.EntityStore EntityStore}. An entity store manages any number of objects for each entity class defined in the model. The store provides access to the primary and secondary indices for each entity class, for example:

EntityStore store = new EntityStore(...);

{@literal PrimaryIndex personBySsn} =
    store.getPrimaryIndex(String.class, Person.class);

A brief example

The following example shows how to define an entity model and how to store and access persistent objects. Exception handling is omitted for brevity.

import java.io.File;
import java.util.HashSet;
import java.util.Set;

import com.sleepycat.db.DatabaseException;
import com.sleepycat.db.Environment;
import com.sleepycat.db.EnvironmentConfig;
import com.sleepycat.persist.EntityCursor;
import com.sleepycat.persist.EntityIndex;
import com.sleepycat.persist.EntityStore;
import com.sleepycat.persist.PrimaryIndex;
import com.sleepycat.persist.SecondaryIndex;
import com.sleepycat.persist.StoreConfig;
import com.sleepycat.persist.model.Entity;
import com.sleepycat.persist.model.Persistent;
import com.sleepycat.persist.model.PrimaryKey;
import com.sleepycat.persist.model.SecondaryKey;
import static com.sleepycat.persist.model.DeleteAction.NULLIFY;
import static com.sleepycat.persist.model.Relationship.ONE_TO_ONE;
import static com.sleepycat.persist.model.Relationship.ONE_TO_MANY;
import static com.sleepycat.persist.model.Relationship.MANY_TO_ONE;
import static com.sleepycat.persist.model.Relationship.MANY_TO_MANY;

// An entity class.
//
{@literal @Entity}
class Person {

    {@literal @PrimaryKey}
    String ssn;

    String name;
    Address address;

    {@literal @SecondaryKey(relate=MANY_TO_ONE, relatedEntity=Person.class)}
    String parentSsn;

    {@literal @SecondaryKey(relate=ONE_TO_MANY)}
    {@literal Set emailAddresses = new HashSet();}

    {@code @SecondaryKey(relate=MANY_TO_MANY, relatedEntity=Employer.class,
                                       onRelatedEntityDelete=NULLIFY)}
    {@code Set employerIds = new HashSet();}

    Person(String name, String ssn, String parentSsn) {
        this.name = name;
        this.ssn = ssn;
        this.parentSsn = parentSsn;
    }

    private Person() {} // For bindings
}

// Another entity class.
//
{@literal @Entity}
class Employer {

    {@literal @PrimaryKey(sequence="ID")}
    long id;

    {@literal @SecondaryKey(relate=ONE_TO_ONE)}
    String name;

    Address address;

    Employer(String name) {
        this.name = name;
    }

    private Employer() {} // For bindings
}

// A persistent class used in other classes.
//
{@literal @Persistent}
class Address {
    String street;
    String city;
    String state;
    int zipCode;
    private Address() {} // For bindings
}

// The data accessor class for the entity model.
//
class PersonAccessor {

    // Person accessors
    //
    {@literal PrimaryIndex personBySsn;}
    {@literal SecondaryIndex personByParentSsn;}
    {@literal SecondaryIndex personByEmailAddresses;}
    {@literal SecondaryIndex personByEmployerIds;}

    // Employer accessors
    //
    {@literal PrimaryIndex employerById;}
    {@literal SecondaryIndex employerByName;}

    // Opens all primary and secondary indices.
    //
    public PersonAccessor(EntityStore store)
        throws DatabaseException {

        personBySsn = store.getPrimaryIndex(
            String.class, Person.class);

        personByParentSsn = store.getSecondaryIndex(
            personBySsn, String.class, "parentSsn");

        personByEmailAddresses = store.getSecondaryIndex(
            personBySsn, String.class, "emailAddresses");

        personByEmployerIds = store.getSecondaryIndex(
            personBySsn, Long.class, "employerIds");

        employerById = store.getPrimaryIndex(
            Long.class, Employer.class);

        employerByName = store.getSecondaryIndex(
            employerById, String.class, "name"); 
    }
}

// Open a transactional Berkeley DB engine environment.
//
EnvironmentConfig envConfig = new EnvironmentConfig();
envConfig.setAllowCreate(true);
envConfig.setTransactional(true);
Environment env = new Environment(new File("/my/data"), envConfig);

// Open a transactional entity store.
//
StoreConfig storeConfig = new StoreConfig();
storeConfig.setAllowCreate(true);
storeConfig.setTransactional(true);
EntityStore store = new EntityStore(env, "PersonStore", storeConfig);

// Initialize the data access object.
//
PersonAccessor dao = new PersonAccessor(store);

// Add a parent and two children using the Person primary index.  Specifying a
// non-null parentSsn adds the child Person to the sub-index of children for
// that parent key.
//
dao.personBySsn.put(new Person("Bob Smith", "111-11-1111", null));
dao.personBySsn.put(new Person("Mary Smith", "333-33-3333", "111-11-1111"));
dao.personBySsn.put(new Person("Jack Smith", "222-22-2222", "111-11-1111"));

// Print the children of a parent using a sub-index and a cursor.
//
{@literal EntityCursor children =}
    dao.personByParentSsn.subIndex("111-11-1111").entities();
try {
    for (Person child : children) {
        System.out.println(child.ssn + ' ' + child.name);
    }
} finally {
    children.close();
}

// Get Bob by primary key using the primary index.
//
Person bob = dao.personBySsn.get("111-11-1111");
assert bob != null;

// Create two employers.  Their primary keys are assigned from a sequence.
//
Employer gizmoInc = new Employer("Gizmo Inc");
Employer gadgetInc = new Employer("Gadget Inc");
dao.employerById.put(gizmoInc);
dao.employerById.put(gadgetInc);

// Bob has two jobs and two email addresses.
//
bob.employerIds.add(gizmoInc.id);
bob.employerIds.add(gadgetInc.id);
bob.emailAddresses.add("bob@bob.com");
bob.emailAddresses.add("bob@gmail.com");

// Update Bob's record.
//
dao.personBySsn.put(bob);

// Bob can now be found by both email addresses.
//
bob = dao.personByEmailAddresses.get("bob@bob.com");
assert bob != null;
bob = dao.personByEmailAddresses.get("bob@gmail.com");
assert bob != null;

// Bob can also be found as an employee of both employers.
//
{@literal EntityIndex employees;}
employees = dao.personByEmployerIds.subIndex(gizmoInc.id);
assert employees.contains("111-11-1111");
employees = dao.personByEmployerIds.subIndex(gadgetInc.id);
assert employees.contains("111-11-1111");

// When an employer is deleted, the onRelatedEntityDelete=NULLIFY for the
// employerIds key causes the deleted ID to be removed from Bob's employerIds.
//
dao.employerById.delete(gizmoInc.id);
bob = dao.personBySsn.get("111-11-1111");
assert !bob.employerIds.contains(gizmoInc.id);

store.close();
env.close();

The example illustrates several characteristics of the DPL:

Which API to use?

The Berkeley DB engine has a {@link com.sleepycat.db Base API}, a {@link com.sleepycat.collections Collections API} and a {@link com.sleepycat.persist Direct Persistence Layer (DPL)}. Follow these guidelines if you are not sure which API to use:

Java 1.5 dependencies

The DPL uses two features of Java 1.5: generic types and annotations. If you wish to avoid using these two Java 1.5 features, the DPL provides options for doing so.

Generic Types

Generic types are used to provide type safety, especially for the {@link com.sleepycat.persist.PrimaryIndex PrimaryIndex}, {@link com.sleepycat.persist.SecondaryIndex SecondaryIndex}, and {@link com.sleepycat.persist.EntityCursor EntityCursor} classes. If you don't wish to use generic types, you can simply not declare your index and cursor objects using generic type parameters. This is the same as using the Java 1.5 Collections Framework without using generic types.

Annotations

If you don't wish to use annotations, you can provide another source of metadata by implementing an {@link com.sleepycat.persist.model.EntityModel EntityModel} class. For example, naming conventions, static members, or an XML configuration file might be used as a source of metadata. However, if you don't use annotations then you won't be able to use bytecode enhancement, which is described next.

Bytecode Enhancement

The persistent fields of a class may be private, package-private, protected or public. The DPL can access persistent fields either by bytecode enhancement or by reflection.

Bytecode enhancement may be used to fully optimize binding performance and to avoid the use of Java reflection. In applications that are CPU bound, avoiding Java reflection can have a significant performance impact.

Bytecode enhancement may be performed either at runtime or at build time (offline). When enhancement is performed at runtime, persistent classes are enhanced as they are loaded. When enhancement is performed offline, class files are enhanced during a post-compilation step. Enhanced classes are used to efficiently access all fields and default constructors, including non-public members.

See {@link com.sleepycat.persist.model.ClassEnhancer ClassEnhancer} for bytecode enhancement configuration details.

If bytecode enhancement is not used as described above, the DPL will use reflection for accessing persistent fields and the default constructor. The {@link java.lang.reflect.AccessibleObject#setAccessible AccessibleObject.setAccessible} method is called by the DPL to enable access to non-public fields and constructors. If you are running under a Java security manager you must configure your security policy to allow the following permission:

{@code permission java.lang.reflect.ReflectPermission "suppressAccessChecks";}

There are three cases where setting the above permission is not required:

  1. If you are not running under a Java Security Manager, then access to non-public members via reflection is not restricted. This is the default for J2SE.

  2. If all persistent fields and default constructors are {@code public} then they can be accessed via reflection without special permissions, even when running under a Java Security Manager. However, declaring {@code public} instance fields is not recommended because it discourages encapsulation.

  3. If bytecode enhancement is used as described above, then reflection will not be used.

It is well known that executing generated code is faster than reflection. However, this performance difference may or may not impact a given application since it may be overshadowed by other factors. Performance testing in a realistic usage scenario is the best way to determine the impact. If you are determined to avoid the use of reflection then option 3 above is recommended.