1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Berkeley DB Concepts</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Getting Started with Berkeley DB" /> 10 <link rel="up" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB" /> 11 <link rel="prev" href="introduction.html" title="Chapter 1. Introduction to Berkeley DB" /> 12 <link rel="next" href="accessmethods.html" title="Access Methods" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Berkeley DB Concepts</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 1. Introduction to Berkeley DB </th> 23 <td width="20%" align="right"> <a accesskey="n" href="accessmethods.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="javadplconcepts"></a>Berkeley DB Concepts</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="javadplconcepts.html#dplenvconcepts">Environments</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="javadplconcepts.html#key-data">Key-Data Pairs</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="javadplconcepts.html#storing-intro">Storing Data</a> 51 </span> 52 </dt> 53 <dt> 54 <span class="sect2"> 55 <a href="javadplconcepts.html#duplicatesintro">Duplicate Data</a> 56 </span> 57 </dt> 58 <dt> 59 <span class="sect2"> 60 <a href="javadplconcepts.html#replacedeleteIntro">Replacing and Deleting Entries</a> 61 </span> 62 </dt> 63 <dt> 64 <span class="sect2"> 65 <a href="javadplconcepts.html#secondary">Secondary Keys</a> 66 </span> 67 </dt> 68 <dt> 69 <span class="sect2"> 70 <a href="javadplconcepts.html#whichapi">Which API Should You Use?</a> 71 </span> 72 </dt> 73 </dl> 74 </div> 75 <p> 76 Before continuing, it is useful to describe some of the 77 concepts you will encounter when building a DB 78 application. 79 </p> 80 <p> 81 The concepts that you will encounter depend upon the actual API 82 that you are using. Some of these concepts are common to both 83 APIs, and so we present those first. Others are only 84 interesting if you use the DPL, while others apply only to 85 the base API. We present each of these in turn. 86 </p> 87 <div class="sect2" lang="en" xml:lang="en"> 88 <div class="titlepage"> 89 <div> 90 <div> 91 <h3 class="title"><a id="dplenvconcepts"></a>Environments</h3> 92 </div> 93 </div> 94 </div> 95 <p> 96 Environments are required for applications built 97 using the DPL. They are optional, but very commonly 98 used, for applications built using the base API. 99 Therefore, it is worthwhile to begin with them. 100 </p> 101 <span> 102 <p> 103 An <span class="emphasis"><em>environment</em></span> is 104 essentially an encapsulation of one or more databases. You 105 open an environment and then you open databases in that environment. 106 When you do so, the databases are created/located in a location relative 107 to the environment's home directory. 108 </p> 109 <p> 110 Environments offer a great many features that a stand-alone DB 111 database cannot offer: 112 </p> 113 <div class="itemizedlist"><ul type="disc"><li><p> 114 Multi-database files. 115 </p><p> 116 It is possible in DB to contain multiple databases in a 117 single physical file on disk. This is desirable for those 118 application that open more than a few handful of databases. 119 However, in order to have more than one database contained in 120 a single physical file, your application 121 <span class="emphasis"><em>must</em></span> use an environment. 122 </p></li><li><p> 123 Multi-thread and multi-process support 124 </p><p> 125 When you use an environment, resources such as the in-memory 126 cache and locks can be shared by all of the databases opened in the 127 environment. The environment allows you to enable 128 subsystems that are designed to allow multiple threads and/or 129 processes to access DB databases. For example, you use an 130 environment to enable the concurrent data store (CDS), the 131 locking subsystem, and/or the shared memory buffer pool. 132 </p></li><li><p> 133 Transactional processing 134 </p><p> 135 DB offers a transactional subsystem that allows for full 136 ACID-protection of your database writes. You use environments to 137 enable the transactional subsystem, and then subsequently to obtain 138 transaction IDs. 139 </p></li><li><p> 140 High availability (replication) support 141 </p><p> 142 DB offers a replication subsystem that enables 143 single-master database replication with multiple read-only 144 copies of the replicated data. You use environments to enable 145 and then manage this subsystem. 146 </p></li><li><p> 147 Logging subsystem 148 </p><p> 149 DB offers write-ahead logging for applications that want to 150 obtain a high-degree of recoverability in the face of an 151 application or system crash. Once enabled, the logging subsystem 152 allows the application to perform two kinds of recovery 153 ("normal" and "catastrophic") through the use of the information 154 contained in the log files. 155 </p></li></ul></div> 156 <p> 157 For more information on these topics, see the 158 <em class="citetitle">Berkeley DB Getting Started with Transaction Processing</em> guide and the 159 <em class="citetitle">Berkeley DB Getting Started with Replicated Applications</em> guide. 160 </p> 161</span> 162 </div> 163 <div class="sect2" lang="en" xml:lang="en"> 164 <div class="titlepage"> 165 <div> 166 <div> 167 <h3 class="title"><a id="key-data"></a>Key-Data Pairs</h3> 168 </div> 169 </div> 170 </div> 171 <p> 172 DB stores and retrieves data using 173 <span class="emphasis"><em>key-data pairs</em></span>. The 174 <span class="emphasis"><em>data</em></span> portion of this is the data 175 that you have decided to store in DB for future 176 retrieval. The <span class="emphasis"><em>key</em></span> is the 177 information that you want to use to look up your 178 stored data once it has been placed inside a DB 179 database. 180 </p> 181 <p> 182 For example, if you were building a database that 183 contained employee information, then the 184 <span class="emphasis"><em>data</em></span> portion is all of the 185 information that you want to store about the employees: 186 name, address, phone numbers, physical location, their 187 manager, and so forth. 188 </p> 189 <p> 190 The <span class="emphasis"><em>key</em></span>, however, is the way that 191 you look up any given employee. You can have more than 192 one key if you wish, but every record in your database must have a 193 primary key. If you are using the DPL, then this key must be unique; that is, 194 it must not be used multiple times in the database. However, if you are using 195 the base API, then this requirement is relaxed. See 196 <a class="xref" href="javadplconcepts.html#duplicatesintro" title="Duplicate Data">Duplicate Data</a> for more 197 information. 198 </p> 199 <p> 200 For example, in the case of an employee database, you would probably use 201 something like the employee identification number as the primary key as this 202 uniquely identifies a given employee. 203 </p> 204 <p> 205 You can optionally also have secondary keys that represent indexes 206 into your database. These keys do not have to be unique 207 to a given record; in fact, they often are not. For 208 example, you might set up the employee's manager's name 209 as a secondary key so that it is easy to locate all 210 the employee's that work for a given manager. 211 </p> 212 </div> 213 <div class="sect2" lang="en" xml:lang="en"> 214 <div class="titlepage"> 215 <div> 216 <div> 217 <h3 class="title"><a id="storing-intro"></a>Storing Data</h3> 218 </div> 219 </div> 220 </div> 221 <p> 222 How you manage your stored information differs 223 significantly, depending on which API you are using. 224 Both APIs ultimately are doing the same thing, but the 225 DPL hides a lot of the details from you. 226 </p> 227 <div class="sect3" lang="en" xml:lang="en"> 228 <div class="titlepage"> 229 <div> 230 <div> 231 <h4 class="title"><a id="dplstore"></a>Storing Data in the DPL</h4> 232 </div> 233 </div> 234 </div> 235 <p> 236 The DPL is used to store Java objects in an 237 underlying series of databases. These databases are 238 accessed using an <code class="classname">EntityStore</code> 239 class object. 240 </p> 241 <p> 242 To use the DPL, you must decorate the classes you 243 want to store with Java annotations that identify them 244 as either an <span class="emphasis"><em>entity class</em></span> or a 245 <span class="emphasis"><em>persistent class</em></span>. 246 </p> 247 <p> 248 Entity classes are classes that have a primary key, and 249 optionally one or more secondary keys. That is, these 250 are the classes that you will save and retrieve directly 251 using the DPL. You identify an entity class using the 252 <code class="literal">@Entity</code> java annotation. 253 </p> 254 <p> 255 Persistent classes are classes used by entity classes. 256 They do not have primary or secondary indices used for 257 object retrieval. Rather, they are stored or retrieved 258 when an entity class makes direct use of them. You 259 identify an persistent class using the 260 <code class="literal">@Persistent</code> java annotation. 261 </p> 262 <p> 263 The primary key for an object is obtained from one of the class' data members. 264 You identify which data member to use as the primary key using the 265 <code class="literal">@PrimaryKey</code> java annotation. 266 </p> 267 <p> 268 Note that all non-transient instance fields of a 269 persistent class, as well as its superclasses and 270 subclasses, are persistent. Static and transient fields 271 are not persistent. The persistent fields of a class 272 may be private, package-private (default access), 273 protected or public. 274 </p> 275 <p> 276 277 Also, simple Java types, such as 278 <code class="classname">java.lang.String</code> and 279 <code class="classname">java.util.Date</code>, are automatically handled as a 280 persistent class when you use them in an entity class; 281 you do not have to do anything special to cause these 282 simple Java objects to be stored in the 283 <code class="classname">EntityStore</code>. 284 285 </p> 286 </div> 287 <div class="sect3" lang="en" xml:lang="en"> 288 <div class="titlepage"> 289 <div> 290 <div> 291 <h4 class="title"><a id="lowlevelstore"></a>Storing Data using the Base API</h4> 292 </div> 293 </div> 294 </div> 295 <p> 296 When you are not using the DPL, both record keys and record data must be byte 297 arrays and are passed to and returned from DB using 298 <code class="classname">DatabaseEntry</code> instances. 299 <code class="classname">DatabaseEntry</code> only supports storage of Java byte arrays. 300 Complex objects must be marshaled using either Java serialization, or more 301 efficiently with the bind APIs provided with DB </p> 302 <p> Database 303 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>. 304 </p> 305 <p> 306 You store records in a <code class="classname">Database</code> by calling one of the 307 put methods on a <code class="classname">Database</code> handle. DB 308 automatically determines the record's proper placement in the database's 309 internal B-Tree using whatever key and data comparison functions that are 310 available to it. 311 </p> 312 <p> 313 You can also retrieve, or get, records using the 314 <code class="classname">Database</code> handle. Gets are performed by providing the 315 key (and sometimes also the data) of the record that you want to retrieve. 316 </p> 317 <p> 318 You can also use cursors for database puts and gets. Cursors are essentially 319 a mechanism by which you can iterate over the records in the database. Like 320 databases and database environments, cursors must be opened and closed. 321 Cursors are managed using the <code class="classname">Cursor</code> class. 322 </p> 323 <p> 324 Databases are described in <a class="xref" href="DB.html" title="Chapter 7. Databases">Databases</a>. Cursors 325 are described in <a class="xref" href="Cursors.html" title="Chapter 9. Using Cursors">Using Cursors</a>. 326 </p> 327 </div> 328 </div> 329 <div class="sect2" lang="en" xml:lang="en"> 330 <div class="titlepage"> 331 <div> 332 <div> 333 <h3 class="title"><a id="duplicatesintro"></a>Duplicate Data</h3> 334 </div> 335 </div> 336 </div> 337 <p> 338 If you are using the base API, then at creation time databases can be configured to 339 allow duplicate data. Remember that DB database records consist of a key/data 340 pair. <span class="emphasis"><em>Duplicate data</em></span>, then, occurs when two or more records have 341 identical keys, but different data. By default, a <code class="classname">Database</code> does 342 not allow duplicate data. 343 </p> 344 <p> 345 If your <code class="classname">Database </code> contains duplicate data, then a simple 346 database get based only on a key returns just the first record that uses that key. To 347 access all duplicate records for that key, you must use a cursor. 348 </p> 349 <p> 350 If you are using the DPL, then you can duplicate date using 351 secondary keys, but not by using the primary key. For more information, see 352 <a class="xref" href="getmultiple.html" title="Retrieving Multiple Objects">Retrieving Multiple Objects</a>. 353 </p> 354 </div> 355 <div class="sect2" lang="en" xml:lang="en"> 356 <div class="titlepage"> 357 <div> 358 <div> 359 <h3 class="title"><a id="replacedeleteIntro"></a>Replacing and Deleting Entries</h3> 360 </div> 361 </div> 362 </div> 363 <p> 364 If you are using the DPL, then replacing a stored entity object simply consists of 365 retrieving it, updating it, then storing it again. To delete the object, use the 366 <code class="methodname">delete()</code> method that is available on either its primary or 367 secondary keys. If you use the <code class="methodname">delete()</code> method available on 368 the secondary key, then all objects referenced by that key are also deleted. 369 See <a class="xref" href="dpl_delete.html" title="Deleting Entity Objects">Deleting Entity Objects</a> 370 for more information. 371 </p> 372 <p> 373 If you are using the base API, then how you replace database records depends on whether 374 duplicate data is allowed in the database. 375 </p> 376 <p> 377 If duplicate data is not allowed in the database, then simply calling 378 <code class="methodname">Database.put()</code> with the appropriate key will cause any 379 existing record to be updated with the new data. Similarly, you can delete a record by 380 providing the appropriate key to the <code class="methodname">Database.delete()</code> 381 method. 382 </p> 383 <p> 384 If duplicate data is allowed in the database, then you must position a cursor to the 385 record that you want to update, and then perform the put operation using the cursor. 386 </p> 387 <p> 388 To delete records using the base API, you can use either <code class="methodname">Database.delete()</code> or 389 <code class="methodname">Cursor.delete()</code>. If duplicate data is not allowed in your 390 database, then these two method behave identically. However, if duplicates are allowed 391 in the database, then <code class="methodname">Database.delete()</code> deletes every record 392 that uses the provided key, while <code class="methodname">Cursor.delete()</code> deletes just 393 the record at which the cursor is currently positioned. 394 </p> 395 </div> 396 <div class="sect2" lang="en" xml:lang="en"> 397 <div class="titlepage"> 398 <div> 399 <div> 400 <h3 class="title"><a id="secondary"></a>Secondary Keys</h3> 401 </div> 402 </div> 403 </div> 404 <p> 405 Secondary keys provide an alternative way to locate information stored in 406 DB, beyond that which is provided by the primary key. Frequently secondary 407 keys refer to more than one record in the database. In this way, you can find 408 all the cars that are green (if you are maintaining an automotive database) or 409 all the people with brown eyes (if you are maintaining a database about people). 410 In other words, secondary keys represent a index into your data. 411 </p> 412 <p> 413 How you create and maintain secondary keys differs significantly, depending on 414 whether you are using the DPL or the base API. 415 </p> 416 <div class="sect3" lang="en" xml:lang="en"> 417 <div class="titlepage"> 418 <div> 419 <div> 420 <h4 class="title"><a id="secondarydpl"></a>Using Secondaries with the DPL</h4> 421 </div> 422 </div> 423 </div> 424 <p> 425 Under the DPL, you declare a particular field to be a secondary key by 426 using the <code class="literal">@SecondaryKey</code> annotation. When you do this, 427 you must declare what kind of an index you are creating. For example, 428 you can declare a secondary key to be part of a 429 <code class="literal">ONE_TO_ONE</code> index, in which case the key is unique to 430 the object. Or you could declare the key to be 431 <code class="literal">MANY_TO_ONE</code>, in which case the key can be used for 432 multiple objects in the data store. 433 </p> 434 <p> 435 Once you have identified secondary keys for a class, you can access 436 those keys by using the <code class="methodname">EntityStore.getSecondaryIndex()</code> 437 method. 438 </p> 439 <p> 440 For more information, see <a class="xref" href="dplindexcreate.html#dplsecondaryidxdecl" title="Declaring Secondary Indexes">Declaring Secondary Indexes</a>. 441 </p> 442 </div> 443 <div class="sect3" lang="en" xml:lang="en"> 444 <div class="titlepage"> 445 <div> 446 <div> 447 <h4 class="title"><a id="secondarybaseapi"></a>Using Secondaries with the Base API.</h4> 448 </div> 449 </div> 450 </div> 451 <p> 452 When you are using the base API, you create and maintain secondary keys using a 453 special type of a database, called a <span class="emphasis"><em>secondary database</em></span>. 454 When you are using secondary databases, the database that holds the data you are 455 indexing is called the <span class="emphasis"><em>primary database</em></span>. 456 </p> 457 <p> 458 You create a secondary database by opening it and associating it with an 459 existing primary database. You must also provide a class that generates the 460 secondary's keys (that is, the index) from primary records. Whenever a 461 record in the primary database is added or changed, DB uses this class 462 to determine what the secondary key should be. 463 </p> 464 <p> 465 When a primary record is created, modified, or deleted, DB automatically 466 updates the secondary database(s) for you as is appropriate for the 467 operation performed on the primary. 468 </p> 469 <p> 470 You manage secondary databases using the 471 <code class="classname">SecondaryDatabase</code> class. You identify how to create keys 472 for your secondary databases by supplying an instance of a class that implements 473 the <code class="classname">SecondaryKeyCreator</code> interface. 474 </p> 475 <p> 476 Secondary databases are described in <a class="xref" href="indexes.html" title="Chapter 10. Secondary Databases">Secondary Databases</a>. 477 </p> 478 </div> 479 </div> 480 <div class="sect2" lang="en" xml:lang="en"> 481 <div class="titlepage"> 482 <div> 483 <div> 484 <h3 class="title"><a id="whichapi"></a>Which API Should You Use?</h3> 485 </div> 486 </div> 487 </div> 488 <p> 489 Of the two APIs that DB makes available to you, we 490 recommend that you use the DPL if all 491 you want to do is make classes with a relatively static schema to 492 be persistent. <span>However, the DPL requires Java 1.5, so 493 if you want to use Java 1.4 then you cannot use the 494 DPL.</span> 495 </p> 496 <p> 497 Further, if you are porting an application between the 498 C or C++ versions of DB and the Java version of 499 this API, then you should not use the DPL as the 500 base API is a much closer match to the other languages 501 available for use with DB. 502 </p> 503 <p> 504 Additionally, if your application uses a highly dynamic 505 schema, then the DPL is probably a poor choice for 506 your application, although the use of Java annotations 507 can make the DPL work a little better for you in this 508 situation. 509 </p> 510 </div> 511 </div> 512 <div class="navfooter"> 513 <hr /> 514 <table width="100%" summary="Navigation footer"> 515 <tr> 516 <td width="40%" align="left"><a accesskey="p" href="introduction.html">Prev</a> </td> 517 <td width="20%" align="center"> 518 <a accesskey="u" href="introduction.html">Up</a> 519 </td> 520 <td width="40%" align="right"> <a accesskey="n" href="accessmethods.html">Next</a></td> 521 </tr> 522 <tr> 523 <td width="40%" align="left" valign="top">Chapter 1. Introduction to Berkeley DB </td> 524 <td width="20%" align="center"> 525 <a accesskey="h" href="index.html">Home</a> 526 </td> 527 <td width="40%" align="right" valign="top"> Access Methods</td> 528 </tr> 529 </table> 530 </div> 531 </body> 532</html> 533