Table of Contents
This document provides an introduction to the concepts and APIs used to store Java objects in Berkeley DB, Java Edition using the Direct Persistence Layer (DPL) which is currently in beta. The DPL is a layer on top of the Berkeley DB, Java Edition library, and as such it offers the same high-quality data guarantees as does JE.
By using the DPL, you can cause any Java type to be persistent without implementing special interfaces. The only real requirement is that each persistent class have a default constructor.
The DPL offers the following features:
Type safe, convenient way of accessing persistent objects.
No hand-coding of bindings is required.
No external schema is required to define primary and secondary keys. Java annotations are used to define all metadata.
Interoperability with external components is supported using the Java collections framework. Any index can be accessed using a standard java.util collection.
Class evolution is explicitly supported. This means you can add fields or widen types automatically and transparently.
You can also perform many incompatible class changes, such as renaming fields or refactoring a single class. This is done using a built-in DPL mechanism called mutations. Mutations are automatically applied as data is accessed so as to avoid downtime to convert large databases during a software upgrade.
Persistent class fields can be private, package-private, protected or public. The DPL can access persistence fields either by bytecode enhancement or by reflection.
The performance of the underlying JE engine is safe-guarded. All DPL operations are mapped directly to the underlying APIs, object bindings are lightweight, and all engine tuning parameters are available.
Java 1.5 generic types and annotations are supported.
Transactions can be used with the DPL.
Note that Sleepycat recommends you use the DPL if all you want to do is make classes with a relatively static schema to be persistent. However, the DPL requires Java 1.5, so if you want to use Java 1.4 then you must use the Berkeley DB, Java Edition APIs.
Further, if you are porting an application between Berkeley DB and Berkeley DB, Java Edition, then you should use the Berkeley DB, Java Edition APIs instead of the DPL APIs. Additionally, if your application uses a highly dynamic schema, then you might want to use the Berkeley DB, Java Edition API instead of the DPL, although the use of annotations can weaken this recommendation to a degree.
The DPL makes use of two features that are specific to Java 1.5.
The Java 1.5 features used by the DPL are:
Generic Types
These are used to provide type safety for index and cursor objects. If you want to use the DPL, and you are content to avoid this feature, do not declare your index and cursor objects using generic type parameters.
Annotations
Annotations allow you to provide metadata about your classes. In particular, you use annotations to identify whether a class is an entity or persistent class. You also use annotations to declare whether data members are primary or secondary keys.
You do not have to use annotations. As an alternative, you can provide an alternate source of metadata by implementing an EntityModel class. Naming conventions, static members or an XML configuration file can be used as a source of metadata if you go this route.