Debian Codegraph @

docs/collections/tutorial/UsingStoredCollections.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 Stored Collections</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="UsingCollectionsAPI.html" title="Using the DB Java Collections API" />
12 <link rel="next" href="SerializedObjectStorage.html" title="Serialized Object Storage" />
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 Stored Collections
23 </th>
24 </tr>
25 <tr>
26 <td width="20%" align="left"><a accesskey="p" href="UsingCollectionsAPI.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="SerializedObjectStorage.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="UsingStoredCollections"></a>
40 Using Stored Collections
41 </h2>
42 </div>
43 </div>
44 </div>
45 <div class="toc">
46 <dl>
47 <dt>
48 <span class="sect2">
49 <a href="UsingStoredCollections.html#StoredCollectionAccessMethods">
50 Stored Collection and Access Methods
51 </a>
52 </span>
53 </dt>
54 <dt>
55 <span class="sect2">
56 <a href="UsingStoredCollections.html#StoredVersusStandardCollections">
57 Stored Collections Versus Standard Java Collections
58 </a>
59 </span>
60 </dt>
61 <dt>
62 <span class="sect2">
63 <a href="UsingStoredCollections.html#StoredCollectionCharacteristics">
64 Other Stored Collection Characteristics
65 </a>
66 </span>
67 </dt>
68 <dt>
69 <span class="sect2">
70 <a href="UsingStoredCollections.html#WhyJavaCollections">
71 Why Java Collections for Berkeley DB
72 </a>
73 </span>
74 </dt>
75 </dl>
76 </div>
77 <p>
78 When a stored collection is created it is based on either a
79
80 <a class="ulink" href="../../java/com/sleepycat/db/Database.html" target="_top">Database</a>
81
82 or a
83
84 <span>
85 <a class="ulink" href="../../java/com/sleepycat/db/SecondaryDatabase.html" target="_top">SecondaryDatabase</a>.
86 </span>
87 When a database is used, the primary key of the database is used as
88 the collection key. When a secondary database is used, the index
89 key is used as the collection key. Indexed collections can be used
90 for reading elements and removing elements but not for adding or
91 updating elements.
92 </p>
93 <div class="sect2" lang="en" xml:lang="en">
94 <div class="titlepage">
95 <div>
96 <div>
97 <h3 class="title"><a id="StoredCollectionAccessMethods"></a>
98 Stored Collection and Access Methods
99 </h3>
100 </div>
101 </div>
102 </div>
103 <p>
104 The use of stored collections is constrained in certain respects as
105 described below.
106 <span>
107 Most of these restrictions have to do with
108 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html" target="_top">List</a>
109
110 interfaces; for
111 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html" target="_top">Map</a>
112
113 interfaces, most all access modes are fully supported since the
114 Berkeley DB model is map-like.
115 </span>
116 </p>
117 <div class="itemizedlist">
118 <ul type="disc">
119 <li>
120 <p>
121 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
122
123 and
124 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html" target="_top">SortedMap</a>
125
126
127 interfaces may only be used if keys are ordered. This means ordered keys are required for creating a
128
129 <a class="ulink" href="../../java/com/sleepycat/collections/StoredSortedEntrySet.html" target="_top">StoredSortedEntrySet</a>,
130 <a class="ulink" href="../../java/com/sleepycat/collections/StoredSortedKeySet.html" target="_top">StoredSortedKeySet</a>,
131 <a class="ulink" href="../../java/com/sleepycat/collections/StoredSortedMap.html" target="_top">StoredSortedMap</a>, or
132 <a class="ulink" href="../../java/com/sleepycat/collections/StoredSortedValueSet.html" target="_top">StoredSortedValueSet</a>.
133 </p>
134 </li>
135 <li>
136 <p>
137 All iterators for stored collections implement the
138 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
139
140 interface as well as the
141 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
142
143 interface.
144 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#hasPrevious()" target="_top">ListIterator.hasPrevious()</a>
145
146 and
147 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#previous()" target="_top">ListIterator.previous()</a>
148
149 work in all cases.
150 <span>
151 However, the following
152 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
153
154 method behavior is dependent on the access method.
155 </span>
156 </p>
157 <div class="itemizedlist">
158 <ul type="circle">
159 <li>
160 <p>
161 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#nextIndex()" target="_top">ListIterator.nextIndex()</a>
162
163 and
164 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#previousIndex()" target="_top">ListIterator.previousIndex()</a>
165
166 only work when record number keys are used, and throw
167 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
168
169 otherwise.
170 </p>
171 </li>
172 <li>
173 <p>
174 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
175
176 inserts before the current position and renumbers following keys if the RECNO-RENUMBER
177 access method is used.
178 </p>
179 </li>
180 <li>
181 <p>
182 For all access methods other than RECNO-RENUMBER:
183 </p>
184 <div class="itemizedlist">
185 <ul type="square">
186 <li>
187 <p>
188 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
189
190 throws
191 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
192
193 if duplicates are not allowed.
194 </p>
195 </li>
196 <li>
197 <p>
198 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
199
200 inserts a duplicate before the current position
201 if duplicates are unsorted.
202 </p>
203 </li>
204 <li>
205 <p>
206 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
207
208 inserts a duplicate in sorted order if
209 duplicates are sorted.
210 </p>
211 </li>
212 </ul>
213 </div>
214 </li>
215 <li>
216 <p>
217 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>
218
219 throws
220 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
221
222 if sorted duplicates are configured, since updating with sorted duplicates would change the
223 iterator position.
224 </p>
225 </li>
226 </ul>
227 </div>
228 </li>
229 <li>
230 <p>
231 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>
232
233 throws
234 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
235
236 if duplicates are sorted.
237 </p>
238 </li>
239 <li>
240 <p>
241 Only the access methods that use a record number key may be used
242 with a
243 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html" target="_top">List</a>
244 <code class="classname">List</code>
245 view.
246 </p>
247 </li>
248 <li>
249 <p>
250 To create a stored List that supports the
251 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a>
252 <code class="methodname">List.add()</code>
253 method, only the RECNO-RENUMBER access method may be used.
254 </p>
255 </li>
256 <li>
257 <p>
258 For List access methods that do not support
259 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a>
260 <code class="methodname">List.add()</code>
261 (RECNO, QUEUE, and BTREE-RECNUM):
262 </p>
263 <div class="itemizedlist">
264 <ul type="circle">
265 <li>
266 <p>
267 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a>
268 <code class="methodname">List.add()</code>
269 and
270 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
271 <code class="methodname">ListIterator.add()</code>
272 always throw
273 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a> .
274 </p>
275 </li>
276 <li>
277 <p>
278 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#remove()" target="_top">List.remove()</a>
279 <code class="methodname">List.remove()</code>
280 and
281 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#remove()" target="_top">ListIterator.remove()</a>
282 <code class="methodname">ListIterator.remove()</code>
283 do not cause list indices to be renumbered. However, iterators will skip
284 the removed values.
285 </p>
286 </li>
287 </ul>
288 </div>
289 <p>
290 For these access methods, stored Lists are most useful as
291 read-only collections where indices are not required to be
292 sequential.
293 </p>
294 </li>
295 <li>
296 <p>
297 When duplicates are allowed the
298 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>
299
300 interfaces are modified in several ways as described in the next
301 section.
302 </p>
303 </li>
304 </ul>
305 </div>
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="StoredVersusStandardCollections"></a>
312 Stored Collections Versus Standard Java Collections
313 </h3>
314 </div>
315 </div>
316 </div>
317 <p>
318 Stored collections have the following differences with the
319 standard Java collection interfaces. Some of these are interface
320 contract violations.
321 </p>
322 <p>
323 The Java collections interface does not support duplicate keys
324 (multi-maps or multi-sets). When the access method allows duplicate
325 keys, the collection interfaces are defined as follows.
326 </p>
327 <div class="itemizedlist">
328 <ul type="disc">
329 <li>
330 <p>
331 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#entrySet()" target="_top">Map.entrySet()</a>
332
333 may contain multiple
334 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html" target="_top">Map.Entry</a>
335
336 objects with the same key.
337 </p>
338 </li>
339 <li>
340 <p>
341 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#keySet()" target="_top">Map.keySet()</a>
342
343 always contains unique keys, it does not contain duplicates.
344 </p>
345 </li>
346 <li>
347 <p>
348 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#values()" target="_top">Map.values()</a>
349
350 contains all values including the values
351 associated with duplicate keys.
352 </p>
353 </li>
354 <li>
355 <p>
356 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>
357
358 appends a duplicate if the key already exists rather than replacing
359 the existing value, and always returns null.
360 </p>
361 </li>
362 <li>
363 <p>
364 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#remove()" target="_top">Map.remove()</a>
365
366 removes all duplicates for the specified key.
367 </p>
368 </li>
369 <li>
370 <p>
371 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#get()" target="_top">Map.get()</a>
372
373 returns the first duplicate for the specified key.
374 </p>
375 </li>
376 <li>
377 <p>
378 <a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html#duplicates(java.lang.Object)" target="_top">StoredMap.duplicates()</a>
379
380 is an additional method for returning the values for a given key as a
381 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>.
382 </p>
383 </li>
384 </ul>
385 </div>
386 <p>
387 Other differences are:
388 </p>
389 <div class="itemizedlist">
390 <ul type="disc">
391 <li>
392 <p>
393 Collection.size() and Map.size() always throws
394 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>.
395 This is because the number of
396 records in a database cannot be determined reliably or
397 cheaply.
398 </p>
399 </li>
400 <li>
401 <p>
402 Because the size() method cannot be used, the bulk operation
403 methods of standard Java collections cannot be passed stored
404 collections as parameters, since the implementations rely on
405 size(). However, the bulk operation methods of stored collections
406 can be passed standard Java collections as parameters.
407 <code class="literal">storedCollection.addAll(standardCollection)</code> is allowed
408 while <code class="literal">standardCollection.addAll(storedCollection)</code> is
409 <span class="emphasis"><em>not</em></span> allowed. This restriction applies to the standard
410 collection constructors that take a Collection parameter (copy
411 constructors), the Map.putAll() method, and the following
412 Collection methods: addAll(), containsAll(), removeAll() and
413 retainAll().
414 </p>
415 </li>
416 <li>
417 <p>
418 The <code class="methodname">ListIterator.nextIndex()</code> method
419 returns <code class="literal">Integer.MAX_VALUE</code>
420 for stored lists when positioned at the end of the list, rather
421 than returning the list size as specified by the ListIterator
422 interface. Again, this is because the database size is not
423 available.
424 </p>
425 </li>
426 <li>
427 <p>
428 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Comparator.html" target="_top">Comparator</a>
429
430 objects cannot be used and the
431 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#comparator()" target="_top">SortedMap.comparator()</a>
432
433 and
434 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html#comparator()" target="_top">SortedSet.comparator()</a>
435
436 methods always return null. The
437 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/Comparable.html" target="_top">Comparable</a>
438
439 interface is not supported. However, Comparators that operate on
440 byte arrays may be specified using
441
442 <span>
443 <a class="ulink" href="../../java/com/sleepycat/db/DatabaseConfig.html#setBtreeComparator(java.util.Comparator)" target="_top">DatabaseConfig.setBtreeComparator</a>.
444 </span>
445 </p>
446 </li>
447 <li>
448 <p>
449 The
450 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/Object.html#equals()" target="_top">Object.equals()</a>
451
452 method is not used to determine whether a key
453 or value is contained in a collection, to locate a value by key,
454 etc. Instead the byte array representation of the keys and values
455 are used. However, the equals() method <span class="emphasis"><em>is</em></span> called for each
456 key and value when comparing two collections for equality. It is
457 the responsibility of the application to make sure that the
458 equals() method returns true if and only if the byte array
459 representations of the two objects are equal. Normally this occurs
460 naturally since the byte array representation is derived from the
461 object's fields.
462 </p>
463 </li>
464 </ul>
465 </div>
466 </div>
467 <div class="sect2" lang="en" xml:lang="en">
468 <div class="titlepage">
469 <div>
470 <div>
471 <h3 class="title"><a id="StoredCollectionCharacteristics"></a>
472 Other Stored Collection Characteristics
473 </h3>
474 </div>
475 </div>
476 </div>
477 <p>
478 The following characteristics of stored collections are
479 extensions of the definitions in the
480 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/package-summary.html" target="_top">java.util</a>
481
482 package. These differences do not violate the Java
483 collections interface contract.
484 </p>
485 <div class="itemizedlist">
486 <ul type="disc">
487 <li>
488 <p>
489 All stored collections are thread safe (can be used by multiple
490 threads concurrently)
491 <span>
492 whenever the Berkeley DB Concurrent Data Store or
493 Transactional Data Store environment is used.
494 </span>
495 Locking is handled by the Berkeley DB
496 environment. To access a collection from multiple threads, creation
497 of synchronized collections using the
498 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collections.html" target="_top">Collections</a>
499
500 class is not necessary
501 <span>
502 except when using the Data Store environment.
503 </span>
504 Iterators, however, should always be used only by a single thread.
505 </p>
506 </li>
507 <li>
508 <p>
509 All stored collections may be read-only if desired by passing
510 false for the writeAllowed parameter of their constructor. Creation
511 of immutable collections using the
512 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collections.html" target="_top">Collections</a>
513
514 class is not necessary.
515 </p>
516 </li>
517 <li>
518 <p>
519 A stored collection is partially read-only if a secondary
520 index is used. Specifically, values may be removed but may not be
521 added or updated. The following methods will throw
522 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>
523
524 when an index is used:
525 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html#add()" target="_top">Collection.add()</a>,
526 <span><a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#set()" target="_top">List.set()</a>,</span>
527 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>
528
529 and
530 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>.
531 </p>
532 </li>
533 <li>
534 <p>
535 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#entrySet()" target="_top">SortedMap.entrySet()</a>
536
537 and
538 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#keySet()" target="_top">SortedMap.keySet()</a>
539
540 return a
541 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>,
542 not just a
543 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Set.html" target="_top">Set</a>
544
545 as specified in Java collections interface. This allows using the
546 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
547
548 methods on the returned collection.
549 </p>
550 </li>
551 <li>
552 <p>
553 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html#values()" target="_top">SortedMap.values()</a>
554
555 returns a
556 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>,
557 not just a
558 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html" target="_top">Collection</a>,
559 whenever the keys of the map can be derived from the values using
560 an entity binding. Note that the sorted set returned is not really
561 a set if duplicates are allowed, since it is technically a
562 collection; however, the
563 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
564
565 methods (for example, subSet()), can still be used.
566 </p>
567 </li>
568 <li>
569 <p>
570 For
571 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedSet.html" target="_top">SortedSet</a>
572
573 and
574 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/SortedMap.html" target="_top">SortedMap</a>
575
576 views, additional subSet() and subMap() methods are provided that
577 allow control over whether keys are treated as inclusive or
578 exclusive values in the key range.
579 </p>
580 </li>
581 <li>
582 <p>
583 Keys and values are stored by value, not by reference. This is
584 because objects that are added to collections are converted to byte
585 arrays (by bindings) and stored in the database. When they are
586 retrieved from the collection they are read from the database and
587 converted from byte arrays to objects. Therefore, the object
588 reference added to a collection will not be the same as the
589 reference later retrieved from the collection.
590 </p>
591 </li>
592 <li>
593 <p>
594 A runtime exception,
595 <a class="ulink" href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html" target="_top">RuntimeExceptionWrapper</a>,
596 is thrown whenever database exceptions occur which are not runtime
597 exceptions. The
598 <a class="ulink" href="../../java/com/sleepycat/util/RuntimeExceptionWrapper.html#getCause()" target="_top">RuntimeExceptionWrapper.getCause()</a>
599
600 method can be called to get the underlying exception.
601 </p>
602 </li>
603 <li>
604 <p>
605 All iterators for stored collections implement the
606 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html" target="_top">ListIterator</a>
607
608 interface as well as the
609 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Iterator.html" target="_top">Iterator</a>
610
611 interface. This is to allow use of the
612 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#hasPrevious()" target="_top">ListIterator.hasPrevious()</a>
613
614 and
615 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#previous()" target="_top">ListIterator.previous()</a>
616
617 methods, which work for all collections
618 since Berkeley DB provides bidirectional cursors.
619 </p>
620 </li>
621 <li>
622 <p>
623 All stored collections have a
624 <a class="ulink" href="../../java/com/sleepycat/collections/StoredCollection.html#iterator(boolean)" target="_top">StoredCollection.iterator(boolean)</a>
625
626 method that allows creating
627 a read-only iterator for a writable collection. For the standard
628 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Collection.html#iterator()" target="_top">Collection.iterator()</a>
629
630 method, the iterator is read-only only
631 when the collection is read-only.
632
633 <span>Read-only iterators are important
634 for using the Berkeley DB Concurrent Data Store environment, since
635 only one write cursors may be open at one time.</span>
636 </p>
637 </li>
638 <li>
639 <p>
640 Iterator stability for stored collections is greater than the
641 iterator stability defined by the Java collections interfaces.
642 Stored iterator stability is the same as the cursor stability
643 defined by Berkeley DB.
644 </p>
645 </li>
646 <li>
647 <p>
648 When an entity binding is used, updating (setting) a value is
649 not allowed if the key in the entity is not equal to the original
650 key. For example, calling
651 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>
652
653 is not allowed when the key parameter is not equal to the key of
654 the entity parameter.
655 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.html#put()" target="_top">Map.put()</a>,
656 <span><a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#set()" target="_top">List.set()</a>,</span>
657 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#set()" target="_top">ListIterator.set()</a>,
658 and
659 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/Map.Entry.html#setValue()" target="_top">Map.Entry.setValue()</a>
660
661 will throw
662 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/IllegalArgumentException.html" target="_top">IllegalArgumentException</a>
663
664 in this situation.
665 </p>
666 </li>
667 <li>
668 <p>
669 Adding and removing items from stored lists is not allowed for
670 sublists. This is simply an unimplemented feature and may be
671 changed in the future. Currently for sublists the following
672 methods throw
673 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/lang/UnsupportedOperationException.html" target="_top">UnsupportedOperationException</a>:
674 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#add()" target="_top">List.add()</a><code class="methodname">List.add()</code>,
675 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/List.html#remove()" target="_top">List.remove()</a><code class="methodname">List.remove()</code>,
676 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#add()" target="_top">ListIterator.add()</a>
677
678 and
679 <a class="ulink" href="http://download.oracle.com/javase/1.5.0/docs/api/java/util/ListIterator.html#remove()" target="_top">ListIterator.remove()</a><code class="methodname">ListIterator.remove()</code>.
680 </p>
681 </li>
682 <li>
683 <p>
684 The
685
686 <span>
687 <a class="ulink" href="../../java/com/sleepycat/collections/StoredList.html#append(java.lang.Object)" target="_top">StoredList.append(java.lang.Object)</a>
688
689 and
690 </span>
691
692 <a class="ulink" href="../../java/com/sleepycat/collections/StoredMap.html#append(java.lang.Object)" target="_top">StoredMap.append(java.lang.Object)</a>
693
694 extension method<span>s</span> allows
695 adding a new record with an automatically assigned key.
696 <span>
697 Record number assignment by the database itself is supported
698 for QUEUE, RECNO and RECNO-RENUMBER databases.
699 </span>
700 An application-defined
701 <a class="ulink" href="../../java/com/sleepycat/collections/PrimaryKeyAssigner.html" target="_top">PrimaryKeyAssigner</a>
702
703 is used to assign the key value.
704 </p>
705 </li>
706 </ul>
707 </div>
708 </div>
709 <div class="sect2" lang="en" xml:lang="en">
710 <div class="titlepage">
711 <div>
712 <div>
713 <h3 class="title"><a id="WhyJavaCollections"></a>
714 Why Java Collections for Berkeley DB
715 </h3>
716 </div>
717 </div>
718 </div>
719 <p>
720 The Java collections interface was chosen as the best Java API
721 for DB given these requirements:
722 </p>
723 <div class="orderedlist">
724 <ol type="1">
725 <li>
726 <p>
727 Provide the Java developer with an API that is as familiar and
728 easy to use as possible.
729 </p>
730 </li>
731 <li>
732 <p>
733 Provide access to all, or a large majority, of the features of
734 the underlying Berkeley DB storage system.
735 </p>
736 </li>
737 <li>
738 <p>
739 Compared to the DB API, provide a higher-level API
740 that is oriented toward Java developers.
741 </p>
742 </li>
743 <li>
744 <p>
745 For ease of use, support object-to-data bindings, per-thread
746 transactions, and some traditional database features such as
747 foreign keys.
748 </p>
749 </li>
750 <li>
751 <p>
752 Provide a thin layer that can be thoroughly tested and which
753 does not significantly impact the reliability and performance of
754 DB.
755 </p>
756 </li>
757 </ol>
758 </div>
759 <p>
760 Admittedly there are several things about the Java Collections
761 API that don't quite fit with DB or with any transactional
762 database, and therefore there are some new rules for applying the
763 Java Collections API. However, these disadvantages are considered
764 to be smaller than the disadvantages of the alternatives:
765 </p>
766 <div class="itemizedlist">
767 <ul type="disc">
768 <li>
769 <p>
770 A new API not based on the Java Collections API could have been
771 designed that maps well to DB but is higher-level.
772 However, this would require designing an entirely new model. The
773 exceptions for using the Java Collections API are considered easier
774 to learn than a whole new model. A new model would also require a
775 long design stabilization period before being as complete and
776 understandable as either the Java Collections API or the DB
777 API.
778 </p>
779 </li>
780 <li>
781 <p>
782 The ODMG API or another object persistence API could have been
783 implemented on top of DB. However, an object persistence
784 implementation would add much code and require a long stabilization
785 period. And while it may work well for applications that require
786 object persistence, it would probably never perform well enough for
787 many other applications.
788 </p>
789 </li>
790 </ul>
791 </div>
792 </div>
793 </div>
794 <div class="navfooter">
795 <hr />
796 <table width="100%" summary="Navigation footer">
797 <tr>
798 <td width="40%" align="left"><a accesskey="p" href="UsingCollectionsAPI.html">Prev</a> </td>
799 <td width="20%" align="center">
800 <a accesskey="u" href="collectionOverview.html">Up</a>
801 </td>
802 <td width="40%" align="right"> <a accesskey="n" href="SerializedObjectStorage.html">Next</a></td>
803 </tr>
804 <tr>
805 <td width="40%" align="left" valign="top">
806 Using the DB Java Collections API
807  </td>
808 <td width="20%" align="center">
809 <a accesskey="h" href="index.html">Home</a>
810 </td>
811 <td width="40%" align="right" valign="top"> 
812 Serialized Object Storage
813 </td>
814 </tr>
815 </table>
816 </div>
817 </body>
818 </html>