Debian Codegraph @

docs/collections/tutorial/UsingCollectionsAPI.html

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