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