Edit File: javadplconcepts.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>
Back to File Manager