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> 7 Using the DB Java Collections API 8 </title> 9 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 10 <meta name="generator" content="DocBook XSL Stylesheets V1.62.4" /> 11 <link rel="home" href="index.html" title="Berkeley DB Collections Tutorial" /> 12 <link rel="up" href="collectionOverview.html" title="Appendix��A.�� API Notes and Details " /> 13 <link rel="previous" href="collectionOverview.html" title="Appendix��A.�� API Notes and Details " /> 14 <link rel="next" href="UsingStoredCollections.html" title=" Using Stored Collections " /> 15 </head> 16 <body> 17 <div class="navheader"> 18 <table width="100%" summary="Navigation header"> 19 <tr> 20 <th colspan="3" align="center"> 21 Using the DB Java Collections API 22 </th> 23 </tr> 24 <tr> 25 <td width="20%" align="left"><a accesskey="p" href="collectionOverview.html">Prev</a>��</td> 26 <th width="60%" align="center">Appendix��A.�� 27 API Notes and Details 28 </th> 29 <td width="20%" align="right">��<a accesskey="n" href="UsingStoredCollections.html">Next</a></td> 30 </tr> 31 </table> 32 <hr /> 33 </div> 34 <div class="sect1" lang="en" xml:lang="en"> 35 <div class="titlepage"> 36 <div> 37 <div> 38 <h2 class="title" style="clear: both"><a id="UsingCollectionsAPI"></a> 39 Using the DB Java Collections API 40 </h2> 41 </div> 42 </div> 43 <div></div> 44 </div> 45 <p> 46 An 47 48 <a href="../../java/com/sleepycat/db/Environment.html" target="_top">Environment</a> 49 50 manages the resources for one or more data stores. A 51 52 <a href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a> 53 54 object 55 represents a single database and is created via a method on the 56 environment object. 57 58 <a href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a> 59 60 objects represent an index associated with a primary database. 61 62 <span> 63 An access method must be chosen for each database and secondary 64 database. 65 </span> 66 67 Primary and secondary databases are then used to create stored 68 collection objects, as described in 69 <a href="UsingStoredCollections.html"> 70 Using Stored Collections 71 </a>. 72 </p> 73 <div class="sect2" lang="en" xml:lang="en"> 74 <div class="titlepage"> 75 <div> 76 <div> 77 <h3 class="title"><a id="UsingTransactions"></a> 78 Using Transactions 79 </h3> 80 </div> 81 </div> 82 <div></div> 83 </div> 84 <p> 85 Once you have an environment, one or more databases, and one or 86 more stored collections, you are ready to access (read and write) 87 stored data. For a transactional environment, a transaction must be 88 started before accessing data, and must be committed or aborted 89 after access is complete. The DB Java Collections API provides several 90 ways of managing transactions. 91 </p> 92 <p> 93 The recommended technique is to use the 94 <a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a> 95 96 class along with your own implementation of the 97 <a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a> 98 99 interface. 100 <a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a> 101 102 will call your 103 <a href="../../java/com/sleepycat/collections/TransactionWorker.html" target="_top">TransactionWorker</a> 104 105 implementation class to perform the data access or work of the 106 transaction. This technique has the following benefits: 107 </p> 108 <div class="itemizedlist"> 109 <ul type="disc"> 110 <li> 111 <p> 112 Transaction exceptions will be handled transparently and 113 retries will be performed when deadlocks are detected. 114 </p> 115 </li> 116 <li> 117 <p> 118 The transaction will automatically be committed if your 119 <a href="../../java/com/sleepycat/collections/TransactionWorker.html#doWork()" target="_top">TransactionWorker.doWork()</a> 120 121 method returns normally, or will be 122 aborted if <tt class="methodname">doWork()</tt> throws an exception. 123 </p> 124 </li> 125 <li> 126 <p> 127 <tt class="classname">TransactionRunner</tt> can be used for non-transactional 128 environments as well, allowing you to write your application 129 independently of the environment. 130 </p> 131 </li> 132 </ul> 133 </div> 134 <p> 135 If you don't want to use 136 <a href="../../java/com/sleepycat/collections/TransactionRunner.html" target="_top">TransactionRunner</a>, 137 the alternative is to use the 138 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html" target="_top">CurrentTransaction</a> 139 140 class. 141 </p> 142 <div class="orderedlist"> 143 <ol type="1"> 144 <li> 145 <p> 146 Obtain a CurrentTransaction instance by calling the 147 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#getInstance(com.sleepycat.db.Environment)" target="_top">CurrentTransaction.getInstance</a> 148 149 method. The instance returned 150 can be used by all threads in a program. 151 </p> 152 </li> 153 <li> 154 <p> 155 Use 156 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#beginTransaction(com.sleepycat.db.TransactionConfig)" target="_top">CurrentTransaction.beginTransaction()</a>, 157 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#commitTransaction()" target="_top">CurrentTransaction.commitTransaction()</a> 158 159 and 160 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#abortTransaction()" target="_top">CurrentTransaction.abortTransaction()</a> 161 162 to directly begin, commit and abort transactions. 163 </p> 164 </li> 165 </ol> 166 </div> 167 <p> 168 If you choose to use CurrentTransaction directly you must handle 169 the 170 171 <a href="../../java/com/sleepycat/db/DeadlockException.html" target="_top">DeadlockException</a> 172 173 exception and perform retries yourself. Also note that 174 CurrentTransaction may only be used in a transactional 175 environment. 176 </p> 177 <p> 178 The DB Java Collections API supports nested transactions. If 179 <a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run(com.sleepycat.collections.TransactionWorker)</a> 180 181 or 182 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#beginTransaction(com.sleepycat.db.TransactionConfig)" target="_top">CurrentTransaction.beginTransaction()</a> 183 , 184 is called while another transaction is active, a child transaction 185 is created. When 186 <a href="../../java/com/sleepycat/collections/TransactionRunner.html#run(com.sleepycat.collections.TransactionWorker)" target="_top">TransactionRunner.run(com.sleepycat.collections.TransactionWorker)</a> 187 188 returns, or when 189 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#commitTransaction()" target="_top">CurrentTransaction.commitTransaction()</a> 190 191 or 192 <a href="../../java/com/sleepycat/collections/CurrentTransaction.html#abortTransaction()" target="_top">CurrentTransaction.abortTransaction()</a> 193 194 is called, the parent transaction becomes active again. Note that 195 because only one transaction is active per-thread, it is impossible 196 to accidentally use a parent transaction while a child transaction 197 is active. 198 </p> 199 <p> 200 The DB Java Collections API supports transaction auto-commit. 201 If no transaction is active and a write operation is requested for 202 a transactional database, auto-commit is used automatically. 203 </p> 204 <p> 205 The DB Java Collections API also supports transaction 206 dirty-read via the 207 <a href="../../java/com/sleepycat/collections/StoredCollections.html" target="_top">StoredCollections</a> 208 209 class. When dirty-read is enabled for a collection, data will be 210 read that has been modified by another transaction but not 211 committed. Using dirty-read can improve concurrency since reading 212 will not wait for other transactions to complete. For a 213 non-transactional container, dirty-read has no effect. See 214 <a href="../../java/com/sleepycat/collections/StoredCollections.html" target="_top">StoredCollections</a> 215 216 for how to create a dirty-read collection. 217 </p> 218 </div> 219 <div class="sect2" lang="en" xml:lang="en"> 220 <div class="titlepage"> 221 <div> 222 <div> 223 <h3 class="title"><a id="TransactionRollback"></a> 224 Transaction Rollback 225 </h3> 226 </div> 227 </div> 228 <div></div> 229 </div> 230 <p> 231 When a transaction is aborted (or rolled back) the application 232 is responsible for discarding references to any data objects that 233 were modified during the transaction. Since the DB Java Collections API 234 treats data by value, not by reference, neither the data 235 objects nor the DB Java Collections API objects contain status 236 information indicating whether the data objects are 1- in sync with 237 the database, 2- dirty (contain changes that have not been written 238 to the database), 3- stale (were read previously but have become 239 out of sync with changes made to the database), or 4- contain 240 changes that cannot be committed because of an aborted 241 transaction. 242 </p> 243 <p> 244 For example, a given data object will reflect the current state 245 of the database after reading it within a transaction. If the 246 object is then modified it will be out of sync with the database. 247 When the modified object is written to the database it will then be 248 in sync again. But if the transaction is aborted the object will 249 then be out of sync with the database. References to objects for aborted 250 transactions 251 should no longer be used. When these objects are needed later they 252 should be read fresh from the database. 253 </p> 254 <p> 255 When an existing stored object is to be updated, special care 256 should be taken to read the data, then modify it, and then write it 257 to the database, all within a single transaction. If a stale data 258 object (an object that was read previously but has since been 259 changed in the database) is modified and then written to the 260 database, database changes may be overwritten unintentionally. 261 </p> 262 <p> 263 When an application enforces rules about concurrent access to 264 specific data objects or all data objects, the rules described here 265 can be relaxed. For example, if the application knows that a 266 certain object is only modified in one place, it may be able to 267 reliably keep a current copy of that object. In that case, it is 268 not necessary to reread the object before updating it. That said, 269 if arbitrary concurrent access is to be supported, the safest 270 approach is to always read data before modifying it within a single 271 transaction. 272 </p> 273 <p> 274 Similar concerns apply to using data that may have become stale. 275 If the application depends on current data, it should be read fresh 276 from the database just before it is used. 277 </p> 278 </div> 279 <div class="sect2" lang="en" xml:lang="en"> 280 <div class="titlepage"> 281 <div> 282 <div> 283 <h3 class="title"><a id="SelectingAccessMethods"></a>Selecting Access Methods</h3> 284 </div> 285 </div> 286 <div></div> 287 </div> 288 <p> 289 For each data store and secondary index, you must choose from one of the 290 access methods in the table below. 291 292 The access method determines not only whether sorted keys or duplicate 293 keys are supported, but also what types of collection views may be used 294 and what restrictions are imposed on the collection views. 295 </p> 296 <div class="informaltable"> 297 <table border="1" width="80%"> 298 <colgroup> 299 <col /> 300 <col /> 301 <col /> 302 <col /> 303 <col /> 304 <col /> 305 </colgroup> 306 <thead> 307 <tr> 308 <th>Access Method</th> 309 <th>Ordered</th> 310 <th>Duplicates</th> 311 <th>Record Numbers</th> 312 <th>Database Type</th> 313 <th><tt class="classname">DatabaseConfig</tt> Method</th> 314 </tr> 315 </thead> 316 <tbody> 317 <tr> 318 <td> 319 BTREE-UNIQUE 320 </td> 321 <td> 322 Yes 323 </td> 324 <td> 325 No 326 </td> 327 <td> 328 No 329 </td> 330 <td> 331 <a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a> 332 </td> 333 <td> 334 None 335 </td> 336 </tr> 337 <tr> 338 <td> 339 BTREE-DUP 340 </td> 341 <td> 342 Yes 343 </td> 344 <td> 345 Yes, Unsorted 346 </td> 347 <td> 348 No 349 </td> 350 <td> 351 <a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a> 352 </td> 353 <td> 354 <a href="../../java/com/sleepycat/db/DatabaseConfig.html#setUnsortedDuplicates(boolean)" target="_top">setUnsortedDuplicates</a> 355 </td> 356 </tr> 357 <tr> 358 <td> 359 BTREE-DUPSORT 360 </td> 361 <td> 362 Yes 363 </td> 364 <td> 365 Yes, Sorted 366 </td> 367 <td> 368 No 369 </td> 370 <td> 371 <a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a> 372 </td> 373 <td> 374 <a href="../../java/com/sleepycat/db/DatabaseConfig.html#setSortedDuplicates(boolean)" target="_top">setSortedDuplicates</a> 375 </td> 376 </tr> 377 <tr> 378 <td> 379 BTREE-RECNUM 380 </td> 381 <td> 382 Yes 383 </td> 384 <td> 385 No 386 </td> 387 <td> 388 Yes, Renumbered 389 </td> 390 <td> 391 <a href="../../java/com/sleepycat/db/DatabaseType.html#BTREE" target="_top">BTREE</a> 392 </td> 393 <td> 394 <a href="../../java/com/sleepycat/db/DatabaseConfig.html#setBtreeRecordNumbers(boolean)" target="_top">setBtreeRecordNumbers</a> 395 </td> 396 </tr> 397 <tr> 398 <td> 399 HASH-UNIQUE 400 </td> 401 <td> 402 No 403 </td> 404 <td> 405 No 406 </td> 407 <td> 408 No 409 </td> 410 <td> 411 <a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">HASH</a> 412 </td> 413 <td> 414 None 415 </td> 416 </tr> 417 <tr> 418 <td> 419 HASH-DUP 420 </td> 421 <td> 422 No 423 </td> 424 <td> 425 Yes, Unsorted 426 </td> 427 <td> 428 No 429 </td> 430 <td> 431 <a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">HASH</a> 432 </td> 433 <td> 434 <a href="../../java/com/sleepycat/db/DatabaseConfig.html#setUnsortedDuplicates(boolean)" target="_top">setUnsortedDuplicates</a> 435 </td> 436 </tr> 437 <tr> 438 <td> 439 HASH-DUPSORT 440 </td> 441 <td> 442 No 443 </td> 444 <td> 445 Yes, Sorted 446 </td> 447 <td> 448 No 449 </td> 450 <td> 451 <a href="../../java/com/sleepycat/db/DatabaseType.html#HASH" target="_top">HASH</a> 452 </td> 453 <td> 454 <a href="../../java/com/sleepycat/db/DatabaseConfig.html#setSortedDuplicates(boolean)" target="_top">setSortedDuplicates</a> 455 </td> 456 </tr> 457 <tr> 458 <td> 459 QUEUE 460 </td> 461 <td> 462 Yes 463 </td> 464 <td> 465 No 466 </td> 467 <td> 468 Yes, Fixed 469 </td> 470 <td> 471 <a href="../../java/com/sleepycat/db/DatabaseType.html#QUEUE" target="_top">QUEUE</a> 472 </td> 473 <td> 474 None 475 </td> 476 </tr> 477 <tr> 478 <td> 479 RECNO 480 </td> 481 <td> 482 Yes 483 </td> 484 <td> 485 No 486 </td> 487 <td> 488 Yes, Fixed 489 </td> 490 <td> 491 <a href="../../java/com/sleepycat/db/DatabaseType.html#RECNO" target="_top">RECNO</a> 492 </td> 493 <td> 494 None 495 </td> 496 </tr> 497 <tr> 498 <td> 499 RECNO-RENUMBER 500 </td> 501 <td> 502 Yes 503 </td> 504 <td> 505 No 506 </td> 507 <td> 508 Yes, Renumbered 509 </td> 510 <td> 511 <a href="../../java/com/sleepycat/db/DatabaseType.html#RECNO" target="_top">RECNO</a> 512 </td> 513 <td> 514 <a href="../../java/com/sleepycat/db/DatabaseConfig.html#setRenumbering(boolean)" target="_top">setRenumbering</a> 515 </td> 516 </tr> 517 </tbody> 518 </table> 519 </div> 520 <p> 521 Please see 522 <span class="html"><a href="../../ref/am_conf/intro.html" target="_top">Available Access Methods</a> in</span> 523 the <i class="citetitle">Berkeley DB Programmer's Reference Guide</i> 524 for more information on access method configuration. 525 </p> 526 </div> 527 <div class="sect2" lang="en" xml:lang="en"> 528 <div class="titlepage"> 529 <div> 530 <div> 531 <h3 class="title"><a id="AccessMethodRestrictions"></a> 532 Access Method Restrictions 533 </h3> 534 </div> 535 </div> 536 <div></div> 537 </div> 538 <p> 539 The restrictions imposed by the access method on the database 540 model are: 541 </p> 542 <div class="itemizedlist"> 543 <ul type="disc"> 544 <li> 545 <p> 546 If keys are ordered then data may be enumerated in key order and 547 key ranges may be used to form subsets of a data store. The 548 <tt class="classname">SortedMap</tt> and <tt class="classname">SortedSet</tt> 549 interfaces are supported for collections with ordered keys. 550 </p> 551 </li> 552 <li> 553 <p> 554 If duplicates are allowed then more than one value may be 555 associated with the same key. This means that the data store cannot 556 be strictly considered a map ��� it is really a multi-map. See 557 <a href="UsingStoredCollections.html"> 558 Using Stored Collections 559 </a> 560 for implications on the use of the collection interfaces. 561 </p> 562 </li> 563 <li> 564 <p> 565 If duplicate keys are allowed for a data store then the data 566 store may not have secondary indices. 567 </p> 568 </li> 569 <li> 570 <p> 571 For secondary indices with duplicates, the duplicates must be 572 sorted. This restriction is imposed by the DB Java Collections API. 573 </p> 574 </li> 575 <li> 576 <p> 577 With sorted duplicates, all values for the same key must be 578 distinct. 579 </p> 580 </li> 581 <li> 582 <p> 583 If duplicates are unsorted, then values for the same key must be 584 distinct. 585 </p> 586 </li> 587 <li> 588 <p> 589 If record number keys are used, the the number of records is 590 limited to the maximum value of an unsigned 32-bit integer. 591 </p> 592 </li> 593 <li> 594 <p> 595 If record number keys are renumbered, then standard List 596 add/remove behavior is supported but concurrency/performance is 597 reduced. 598 </p> 599 </li> 600 </ul> 601 </div> 602 <p> 603 See 604 <a href="UsingStoredCollections.html"> 605 Using Stored Collections 606 </a> 607 for more information on how access methods impact the use of stored 608 collections. 609 </p> 610 </div> 611 </div> 612 <div class="navfooter"> 613 <hr /> 614 <table width="100%" summary="Navigation footer"> 615 <tr> 616 <td width="40%" align="left"><a accesskey="p" href="collectionOverview.html">Prev</a>��</td> 617 <td width="20%" align="center"> 618 <a accesskey="u" href="collectionOverview.html">Up</a> 619 </td> 620 <td width="40%" align="right">��<a accesskey="n" href="UsingStoredCollections.html">Next</a></td> 621 </tr> 622 <tr> 623 <td width="40%" align="left" valign="top">Appendix��A.�� 624 API Notes and Details 625 ��</td> 626 <td width="20%" align="center"> 627 <a accesskey="h" href="index.html">Home</a> 628 </td> 629 <td width="40%" align="right" valign="top">�� 630 Using Stored Collections 631 </td> 632 </tr> 633 </table> 634 </div> 635 </body> 636</html> 637