1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
|
<?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.73.2" />
<link rel="start" href="index.html" title="Getting Started with Berkeley DB" />
<link rel="up" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB" />
<link rel="prev" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB" />
<link rel="next" href="accessmethods.html" title="Access Methods" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.1.6.1</p>
</div>
<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 class="toc">
<dl>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#dplenvconcepts">Environments</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#key-data">Key-Data Pairs</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#storing-intro">Storing Data</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#duplicatesintro">Duplicate Data</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#replacedeleteIntro">Replacing and Deleting Entries</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#secondary">Secondary Keys</a>
</span>
</dt>
<dt>
<span class="sect2">
<a href="javadplconcepts.html#whichapi">Which API Should You Use?</a>
</span>
</dt>
</dl>
</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>
<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
<em class="citetitle">Berkeley DB Getting Started with Transaction Processing</em> guide and the
<em class="citetitle">Berkeley DB Getting Started with Replicated Applications</em> 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>
<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 class="xref" href="javadplconcepts.html#duplicatesintro" title="Duplicate Data">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>
<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>
<p>
The DPL is used to store Java objects in an
underlying series of databases. These databases are
accessed using an <code class="classname">EntityStore</code>
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
<code class="literal">@Entity</code> 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
<code class="literal">@Persistent</code> 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
<code class="literal">@PrimaryKey</code> 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
<code class="classname">java.lang.String</code> and
<code class="classname">java.util.Date</code>, 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
<code class="classname">EntityStore</code>.
</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>
<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
<code class="classname">DatabaseEntry</code> instances.
<code class="classname">DatabaseEntry</code> 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 <code class="literal">byte</code> array conversion are described in <a class="xref" href="DBEntry.html" title="Chapter 8. Database Records">Database Records</a>.
</p>
<p>
You store records in a <code class="classname">Database</code> by calling one of the
put methods on a <code class="classname">Database</code> 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
<code class="classname">Database</code> 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 <code class="classname">Cursor</code> class.
</p>
<p>
Databases are described in <a class="xref" href="databases.html" title="Chapter 7. Databases">Databases</a>. Cursors
are described in <a class="xref" href="Cursors.html" title="Chapter 9. Using Cursors">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>
<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 <code class="classname">Database</code> does
not allow duplicate data.
</p>
<p>
If your <code class="classname">Database </code> 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 class="xref" href="getmultiple.html" title="Retrieving Multiple Objects">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>
<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
<code class="methodname">delete()</code> method that is available on either its primary or
secondary keys. If you use the <code class="methodname">delete()</code> method available on
the secondary key, then all objects referenced by that key are also deleted.
See <a class="xref" href="dpl_delete.html" title="Deleting Entity Objects">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
<code class="methodname">Database.put()</code> 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 <code class="methodname">Database.delete()</code>
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 <code class="methodname">Database.delete()</code> or
<code class="methodname">Cursor.delete()</code>. If duplicate data is not allowed in your
database, then these two method behave identically. However, if duplicates are allowed
in the database, then <code class="methodname">Database.delete()</code> deletes every record
that uses the provided key, while <code class="methodname">Cursor.delete()</code> 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>
<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>
<p>
Under the DPL, you declare a particular field to be a secondary key by
using the <code class="literal">@SecondaryKey</code> 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
<code class="literal">ONE_TO_ONE</code> index, in which case the key is unique to
the object. Or you could declare the key to be
<code class="literal">MANY_TO_ONE</code>, 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 <code class="methodname">EntityStore.getSecondaryIndex()</code>
method.
</p>
<p>
For more information, see <a class="xref" href="dplindexcreate.html#dplsecondaryidxdecl" title="Declaring Secondary Indexes">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>
<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
<code class="classname">SecondaryDatabase</code> class. You identify how to create keys
for your secondary databases by supplying an instance of a class that implements
the <code class="classname">SecondaryKeyCreator</code> interface.
</p>
<p>
Secondary databases are described in <a class="xref" href="indexes.html" title="Chapter 10. Secondary Databases">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>
<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. <span>However, the DPL requires Java 1.5, so
if you want to use Java 1.4 then you cannot use the
DPL.</span>
</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>
|
