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