505 lines
25 KiB
HTML
505 lines
25 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Berkeley DB Concepts</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.62.4" />
|
||
<link rel="home" href="index.html" title="Getting Started with Berkeley DB" />
|
||
<link rel="up" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB " />
|
||
<link rel="previous" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB " />
|
||
<link rel="next" href="accessmethods.html" title="Access Methods" />
|
||
</head>
|
||
<body>
|
||
<div class="navheader">
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Berkeley DB Concepts</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 1. Introduction to Berkeley DB </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="accessmethods.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="javadplconcepts"></a>Berkeley DB Concepts</h2>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
Before continuing, it is useful to describe some of the
|
||
concepts you will encounter when building a DB
|
||
application.
|
||
</p>
|
||
<p>
|
||
The concepts that you will encounter depend upon the actual API
|
||
that you are using. Some of these concepts are common to both
|
||
APIs, and so we present those first. Others are only
|
||
interesting if you use the DPL, while others apply only to
|
||
the base API. We present each of these in turn.
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="dplenvconcepts"></a>Environments</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
Environments are required for applications built
|
||
using the DPL. They are optional, but very commonly
|
||
used, for applications built using the base API.
|
||
Therefore, it is worthwhile to begin with them.
|
||
</p>
|
||
<span>
|
||
<p>
|
||
An <span class="emphasis"><em>environment</em></span> is
|
||
essentially an encapsulation of one or more databases. You
|
||
open an environment and then you open databases in that environment.
|
||
When you do so, the databases are created/located in a location relative
|
||
to the environment's home directory.
|
||
</p>
|
||
<p>
|
||
Environments offer a great many features that a stand-alone DB
|
||
database cannot offer:
|
||
</p>
|
||
<div class="itemizedlist"><ul type="disc"><li><p>
|
||
Multi-database files.
|
||
</p><p>
|
||
It is possible in DB to contain multiple databases in a
|
||
single physical file on disk. This is desirable for those
|
||
application that open more than a few handful of databases.
|
||
However, in order to have more than one database contained in
|
||
a single physical file, your application
|
||
<span class="emphasis"><em>must</em></span> use an environment.
|
||
</p></li><li><p>
|
||
Multi-thread and multi-process support
|
||
</p><p>
|
||
When you use an environment, resources such as the in-memory
|
||
cache and locks can be shared by all of the databases opened in the
|
||
environment. The environment allows you to enable
|
||
subsystems that are designed to allow multiple threads and/or
|
||
processes to access DB databases. For example, you use an
|
||
environment to enable the concurrent data store (CDS), the
|
||
locking subsystem, and/or the shared memory buffer pool.
|
||
</p></li><li><p>
|
||
Transactional processing
|
||
</p><p>
|
||
DB offers a transactional subsystem that allows for full
|
||
ACID-protection of your database writes. You use environments to
|
||
enable the transactional subsystem, and then subsequently to obtain
|
||
transaction IDs.
|
||
</p></li><li><p>
|
||
High availability (replication) support
|
||
</p><p>
|
||
DB offers a replication subsystem that enables
|
||
single-master database replication with multiple read-only
|
||
copies of the replicated data. You use environments to enable
|
||
and then manage this subsystem.
|
||
</p></li><li><p>
|
||
Logging subsystem
|
||
</p><p>
|
||
DB offers write-ahead logging for applications that want to
|
||
obtain a high-degree of recoverability in the face of an
|
||
application or system crash. Once enabled, the logging subsystem
|
||
allows the application to perform two kinds of recovery
|
||
("normal" and "catastrophic") through the use of the information
|
||
contained in the log files.
|
||
</p></li></ul></div>
|
||
<p>
|
||
For more information on these topics, see the
|
||
<i class="citetitle">Berkeley DB Getting Started with Transaction Processing</i> guide and the
|
||
<i class="citetitle">Berkeley DB Getting Started with Replicated Applications</i> guide.
|
||
</p>
|
||
</span>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="key-data"></a>Key-Data Pairs</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
DB stores and retrieves data using
|
||
<span class="emphasis"><em>key-data pairs</em></span>. The
|
||
<span class="emphasis"><em>data</em></span> portion of this is the data
|
||
that you have decided to store in DB for future
|
||
retrieval. The <span class="emphasis"><em>key</em></span> is the
|
||
information that you want to use to look up your
|
||
stored data once it has been placed inside a DB
|
||
database.
|
||
</p>
|
||
<p>
|
||
For example, if you were building a database that
|
||
contained employee information, then the
|
||
<span class="emphasis"><em>data</em></span> portion is all of the
|
||
information that you want to store about the employees:
|
||
name, address, phone numbers, physical location, their
|
||
manager, and so forth.
|
||
</p>
|
||
<p>
|
||
The <span class="emphasis"><em>key</em></span>, however, is the way that
|
||
you look up any given employee. You can have more than
|
||
one key if you wish, but every record in your database must have a
|
||
primary key. If you are using the DPL, then this key must be unique; that is,
|
||
it must not be used multiple times in the database. However, if you are using
|
||
the base API, then this requirement is relaxed. See
|
||
<a href="javadplconcepts.html#duplicatesintro">Duplicate Data</a> for more
|
||
information.
|
||
</p>
|
||
<p>
|
||
For example, in the case of an employee database, you would probably use
|
||
something like the employee identification number as the primary key as this
|
||
uniquely identifies a given employee.
|
||
</p>
|
||
<p>
|
||
You can optionally also have secondary keys that represent indexes
|
||
into your database. These keys do not have to be unique
|
||
to a given record; in fact, they often are not. For
|
||
example, you might set up the employee's manager's name
|
||
as a secondary key so that it is easy to locate all
|
||
the employee's that work for a given manager.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="storing-intro"></a>Storing Data</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
How you manage your stored information differs
|
||
significantly, depending on which API you are using.
|
||
Both APIs ultimately are doing the same thing, but the
|
||
DPL hides a lot of the details from you.
|
||
</p>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="dplstore"></a>Storing Data in the DPL</h4>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
The DPL is used to store Java objects in an
|
||
underlying series of databases. These databases are
|
||
accessed using an <tt class="classname">EntityStore</tt>
|
||
class object.
|
||
</p>
|
||
<p>
|
||
To use the DPL, you must decorate the classes you
|
||
want to store with Java annotations that identify them
|
||
as either an <span class="emphasis"><em>entity class</em></span> or a
|
||
<span class="emphasis"><em>persistent class</em></span>.
|
||
</p>
|
||
<p>
|
||
Entity classes are classes that have a primary key, and
|
||
optionally one or more secondary keys. That is, these
|
||
are the classes that you will save and retrieve directly
|
||
using the DPL. You identify an entity class using the
|
||
<tt class="literal">@Entity</tt> java annotation.
|
||
</p>
|
||
<p>
|
||
Persistent classes are classes used by entity classes.
|
||
They do not have primary or secondary indices used for
|
||
object retrieval. Rather, they are stored or retrieved
|
||
when an entity class makes direct use of them. You
|
||
identify an persistent class using the
|
||
<tt class="literal">@Persistent</tt> java annotation.
|
||
</p>
|
||
<p>
|
||
The primary key for an object is obtained from one of the class' data members.
|
||
You identify which data member to use as the primary key using the
|
||
<tt class="literal">@PrimaryKey</tt> java annotation.
|
||
</p>
|
||
<p>
|
||
Note that all non-transient instance fields of a
|
||
persistent class, as well as its superclasses and
|
||
subclasses, are persistent. Static and transient fields
|
||
are not persistent. The persistent fields of a class
|
||
may be private, package-private (default access),
|
||
protected or public.
|
||
</p>
|
||
<p>
|
||
|
||
Also, simple Java types, such as
|
||
<tt class="classname">java.lang.String</tt> and
|
||
<tt class="classname">java.util.Date</tt>, are automatically handled as a
|
||
persistent class when you use them in an entity class;
|
||
you do not have to do anything special to cause these
|
||
simple Java objects to be stored in the
|
||
<tt class="classname">EntityStore</tt>.
|
||
|
||
</p>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="lowlevelstore"></a>Storing Data using the Base API</h4>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
When you are not using the DPL, both record keys and record data must be byte
|
||
arrays and are passed to and returned from DB using
|
||
<tt class="classname">DatabaseEntry</tt> instances.
|
||
<tt class="classname">DatabaseEntry</tt> only supports storage of Java byte arrays.
|
||
Complex objects must be marshaled using either Java serialization, or more
|
||
efficiently with the bind APIs provided with DB </p>
|
||
<p> Database
|
||
records and <tt class="literal">byte</tt> array conversion are described in <a href="DBEntry.html">Database Records</a>.
|
||
</p>
|
||
<p>
|
||
You store records in a <tt class="classname">Database</tt> by calling one of the
|
||
put methods on a <tt class="classname">Database</tt> handle. DB
|
||
automatically determines the record's proper placement in the database's
|
||
internal B-Tree using whatever key and data comparison functions that are
|
||
available to it.
|
||
</p>
|
||
<p>
|
||
You can also retrieve, or get, records using the
|
||
<tt class="classname">Database</tt> handle. Gets are performed by providing the
|
||
key (and sometimes also the data) of the record that you want to retrieve.
|
||
</p>
|
||
<p>
|
||
You can also use cursors for database puts and gets. Cursors are essentially
|
||
a mechanism by which you can iterate over the records in the database. Like
|
||
databases and database environments, cursors must be opened and closed.
|
||
Cursors are managed using the <tt class="classname">Cursor</tt> class.
|
||
</p>
|
||
<p>
|
||
Databases are described in <a href="DB.html">Databases</a>. Cursors
|
||
are described in <a href="Cursors.html">Using Cursors</a>.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="duplicatesintro"></a>Duplicate Data</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
If you are using the base API, then at creation time databases can be configured to
|
||
allow duplicate data. Remember that DB database records consist of a key/data
|
||
pair. <span class="emphasis"><em>Duplicate data</em></span>, then, occurs when two or more records have
|
||
identical keys, but different data. By default, a <tt class="classname">Database</tt> does
|
||
not allow duplicate data.
|
||
</p>
|
||
<p>
|
||
If your <tt class="classname">Database </tt> contains duplicate data, then a simple
|
||
database get based only on a key returns just the first record that uses that key. To
|
||
access all duplicate records for that key, you must use a cursor.
|
||
</p>
|
||
<p>
|
||
If you are using the DPL, then you can duplicate date using
|
||
secondary keys, but not by using the primary key. For more information, see
|
||
<a href="getmultiple.html">Retrieving Multiple Objects</a>.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="replacedeleteIntro"></a>Replacing and Deleting Entries</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
If you are using the DPL, then replacing a stored entity object simply consists of
|
||
retrieving it, updating it, then storing it again. To delete the object, use the
|
||
<tt class="methodname">delete()</tt> method that is available on either its primary or
|
||
secondary keys. If you use the <tt class="methodname">delete()</tt> method available on
|
||
the secondary key, then all objects referenced by that key are also deleted.
|
||
See <a href="dpl_delete.html">Deleting Entity Objects</a>
|
||
for more information.
|
||
</p>
|
||
<p>
|
||
If you are using the base API, then how you replace database records depends on whether
|
||
duplicate data is allowed in the database.
|
||
</p>
|
||
<p>
|
||
If duplicate data is not allowed in the database, then simply calling
|
||
<tt class="methodname">Database.put()</tt> with the appropriate key will cause any
|
||
existing record to be updated with the new data. Similarly, you can delete a record by
|
||
providing the appropriate key to the <tt class="methodname">Database.delete()</tt>
|
||
method.
|
||
</p>
|
||
<p>
|
||
If duplicate data is allowed in the database, then you must position a cursor to the
|
||
record that you want to update, and then perform the put operation using the cursor.
|
||
</p>
|
||
<p>
|
||
To delete records using the base API, you can use either <tt class="methodname">Database.delete()</tt> or
|
||
<tt class="methodname">Cursor.delete()</tt>. If duplicate data is not allowed in your
|
||
database, then these two method behave identically. However, if duplicates are allowed
|
||
in the database, then <tt class="methodname">Database.delete()</tt> deletes every record
|
||
that uses the provided key, while <tt class="methodname">Cursor.delete()</tt> deletes just
|
||
the record at which the cursor is currently positioned.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="secondary"></a>Secondary Keys</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
Secondary keys provide an alternative way to locate information stored in
|
||
DB, beyond that which is provided by the primary key. Frequently secondary
|
||
keys refer to more than one record in the database. In this way, you can find
|
||
all the cars that are green (if you are maintaining an automotive database) or
|
||
all the people with brown eyes (if you are maintaining a database about people).
|
||
In other words, secondary keys represent a index into your data.
|
||
</p>
|
||
<p>
|
||
How you create and maintain secondary keys differs significantly, depending on
|
||
whether you are using the DPL or the base API.
|
||
</p>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="secondarydpl"></a>Using Secondaries with the DPL</h4>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
Under the DPL, you declare a particular field to be a secondary key by
|
||
using the <tt class="literal">@SecondaryKey</tt> annotation. When you do this,
|
||
you must declare what kind of an index you are creating. For example,
|
||
you can declare a secondary key to be part of a
|
||
<tt class="literal">ONE_TO_ONE</tt> index, in which case the key is unique to
|
||
the object. Or you could declare the key to be
|
||
<tt class="literal">MANY_TO_ONE</tt>, in which case the key can be used for
|
||
multiple objects in the data store.
|
||
</p>
|
||
<p>
|
||
Once you have identified secondary keys for a class, you can access
|
||
those keys by using the <tt class="methodname">EntityStore.getSecondaryIndex()</tt>
|
||
method.
|
||
</p>
|
||
<p>
|
||
For more information, see <a href="dplindexcreate.html#dplsecondaryidxdecl">Declaring Secondary Indexes</a>.
|
||
</p>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="secondarybaseapi"></a>Using Secondaries with the Base API.</h4>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
When you are using the base API, you create and maintain secondary keys using a
|
||
special type of a database, called a <span class="emphasis"><em>secondary database</em></span>.
|
||
When you are using secondary databases, the database that holds the data you are
|
||
indexing is called the <span class="emphasis"><em>primary database</em></span>.
|
||
</p>
|
||
<p>
|
||
You create a secondary database by opening it and associating it with an
|
||
existing primary database. You must also provide a class that generates the
|
||
secondary's keys (that is, the index) from primary records. Whenever a
|
||
record in the primary database is added or changed, DB uses this class
|
||
to determine what the secondary key should be.
|
||
</p>
|
||
<p>
|
||
When a primary record is created, modified, or deleted, DB automatically
|
||
updates the secondary database(s) for you as is appropriate for the
|
||
operation performed on the primary.
|
||
</p>
|
||
<p>
|
||
You manage secondary databases using the
|
||
<tt class="classname">SecondaryDatabase</tt> class. You identify how to create keys
|
||
for your secondary databases by supplying an instance of a class that implements
|
||
the <tt class="classname">SecondaryKeyCreator</tt> interface.
|
||
</p>
|
||
<p>
|
||
Secondary databases are described in <a href="indexes.html">Secondary Databases</a>.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="whichapi"></a>Which API Should You Use?</h3>
|
||
</div>
|
||
</div>
|
||
<div></div>
|
||
</div>
|
||
<p>
|
||
Of the two APIs that DB makes available to you, we
|
||
recommend that 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 cannot use the DPL.
|
||
</p>
|
||
<p>
|
||
Further, if you are porting an application between the
|
||
C or C++ versions of DB and the Java version of
|
||
this API, then you should not use the DPL as the
|
||
base API is a much closer match to the other languages
|
||
available for use with DB.
|
||
</p>
|
||
<p>
|
||
Additionally, if your application uses a highly dynamic
|
||
schema, then the DPL is probably a poor choice for
|
||
your application, although the use of Java annotations
|
||
can make the DPL work a little better for you in this
|
||
situation.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="introduction.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="accessmethods.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Chapter 1. Introduction to Berkeley DB </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Access Methods</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|