1 /*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2002, 2013 Oracle and/or its affiliates. All rights reserved. 5 * 6 * $Id$ 7 */ 8 9 package com.sleepycat.db; 10 11 import com.sleepycat.db.internal.Db; 12 import com.sleepycat.db.internal.DbConstants; 13 import com.sleepycat.db.internal.DbEnv; 14 import com.sleepycat.db.internal.DbTxn; 15 import com.sleepycat.db.internal.DbUtil; 16 17 /** 18 Specify the attributes of a database. 19 */ 20 public class DatabaseConfig implements Cloneable { 21 /* 22 * For internal use, final to allow null as a valid value for 23 * the config parameter. 24 */ 25 /** 26 An instance created using the default constructor is initialized 27 with the system's default settings. 28 */ 29 public static final DatabaseConfig DEFAULT = new DatabaseConfig(); 30 31 /* package */ checkNull(DatabaseConfig config)32 static DatabaseConfig checkNull(DatabaseConfig config) { 33 return (config == null) ? DEFAULT : config; 34 } 35 36 /* Parameters */ 37 private DatabaseType type = DatabaseType.UNKNOWN; 38 private int mode = 0644; 39 private int btMinKey = 0; 40 private int byteOrder = 0; 41 private long cacheSize = 0L; 42 private java.io.File createDir = null; 43 private int cacheCount = 0; 44 private java.io.OutputStream errorStream = null; 45 private String errorPrefix = null; 46 private int hashFillFactor = 0; 47 private int hashNumElements = 0; 48 private long heapSize = 0L; 49 private int heapRegionSize = 0; 50 private java.io.OutputStream messageStream = null; 51 private Boolean noWaitDbExclusiveLock = null; 52 private int pageSize = 0; 53 private java.io.File[] partitionDirs = null; 54 private DatabaseEntry partitionKeys = null; 55 private int partitionParts = 0; 56 private String password = null; 57 private CacheFilePriority priority = null; 58 private int queueExtentSize = 0; 59 private int recordDelimiter = 0; 60 private int recordLength = 0; 61 private int recordPad = -1; // Zero is a valid, non-default value. 62 private java.io.File recordSource = null; 63 64 /* Flags */ 65 private boolean allowCreate = false; 66 private boolean btreeRecordNumbers = false; 67 private boolean checksum = false; 68 private boolean readUncommitted = false; 69 private boolean encrypted = false; 70 private boolean exclusiveCreate = false; 71 private boolean multiversion = false; 72 private boolean noMMap = false; 73 private boolean queueInOrder = false; 74 private boolean readOnly = false; 75 private boolean renumbering = false; 76 private boolean reverseSplitOff = false; 77 private boolean sortedDuplicates = false; 78 private boolean snapshot = false; 79 private boolean unsortedDuplicates = false; 80 private boolean transactional = false; 81 private boolean transactionNotDurable = false; 82 private boolean truncate = false; 83 84 /* Callbacks */ 85 private java.util.Comparator btreeComparator = null; 86 private BtreeCompressor btreeCompressor = null; 87 private BtreePrefixCalculator btreePrefixCalculator = null; 88 private java.util.Comparator duplicateComparator = null; 89 private FeedbackHandler feedbackHandler = null; 90 private ErrorHandler errorHandler = null; 91 private MessageHandler messageHandler = null; 92 private PartitionHandler partitionHandler = null; 93 private java.util.Comparator hashComparator = null; 94 private Hasher hasher = null; 95 private RecordNumberAppender recnoAppender = null; 96 private PanicHandler panicHandler = null; 97 98 /** 99 An instance created using the default constructor is initialized with 100 the system's default settings. 101 */ DatabaseConfig()102 public DatabaseConfig() { 103 } 104 105 /** 106 * Returns a copy of this configuration object. 107 */ cloneConfig()108 public DatabaseConfig cloneConfig() { 109 try { 110 return (DatabaseConfig) super.clone(); 111 } catch (CloneNotSupportedException willNeverOccur) { 112 return null; 113 } 114 } 115 116 /** 117 Configure the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method to create 118 the database if it does not already exist. 119 <p> 120 @param allowCreate 121 If true, configure the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method to 122 create the database if it does not already exist. 123 */ setAllowCreate(final boolean allowCreate)124 public void setAllowCreate(final boolean allowCreate) { 125 this.allowCreate = allowCreate; 126 } 127 128 /** 129 Return true if the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method is configured 130 to create the database if it does not already exist. 131 <p> 132 This method may be called at any time during the life of the application. 133 <p> 134 @return 135 True if the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method is configured 136 to create the database if it does not already exist. 137 */ getAllowCreate()138 public boolean getAllowCreate() { 139 return allowCreate; 140 } 141 142 /** 143 By default, a byte by byte lexicographic comparison is used for 144 btree keys. To customize the comparison, supply a different 145 Comparator. 146 <p> 147 The <code>compare</code> method is passed the byte arrays representing 148 keys that are stored in the database. If you know how your data is 149 organized in the byte array, then you can write a comparison routine that 150 directly examines the contents of the arrays. Otherwise, you have to 151 reconstruct your original objects, and then perform the comparison. 152 */ setBtreeComparator(final java.util.Comparator btreeComparator)153 public void setBtreeComparator(final java.util.Comparator btreeComparator) { 154 this.btreeComparator = btreeComparator; 155 } 156 157 /** 158 Return the custom Comparator used for btree keys. 159 <p> 160 @return the custom Comparator used for btree keys, or null if the default 161 comparison function will be used. 162 */ getBtreeComparator()163 public java.util.Comparator getBtreeComparator() { 164 return btreeComparator; 165 } 166 167 /** 168 Set the minimum number of key/data pairs intended to be stored on any 169 single Btree leaf page. 170 <p> 171 This value is used to determine if key or data items will be stored 172 on overflow pages instead of Btree leaf pages. The value must be 173 at least 2; if the value is not explicitly set, a value of 2 is used. 174 <p> 175 This method configures a database, not only operations performed using 176 the specified {@link com.sleepycat.db.Database Database} handle. 177 <p> 178 This method may not be called after the database is opened. 179 If the database already exists when it is opened, 180 the information specified to this method will be ignored. 181 <p> 182 @param btMinKey 183 The minimum number of key/data pairs intended to be stored on any 184 single Btree leaf page. 185 */ setBtreeMinKey(final int btMinKey)186 public void setBtreeMinKey(final int btMinKey) { 187 this.btMinKey = btMinKey; 188 } 189 190 /** 191 Return the minimum number of key/data pairs intended to be stored 192 on any single Btree leaf page. 193 <p> 194 This method may be called at any time during the life of the application. 195 <p> 196 @return 197 The minimum number of key/data pairs intended to be stored 198 on any single Btree leaf page. 199 */ getBtreeMinKey()200 public int getBtreeMinKey() { 201 return btMinKey; 202 } 203 204 /** 205 Set the byte order for integers in the stored database metadata. 206 <p> 207 The host byte order of the machine where the process is running will 208 be used if no byte order is set. 209 <p> 210 <b> 211 The access methods provide no guarantees about the byte ordering of the 212 application data stored in the database, and applications are 213 responsible for maintaining any necessary ordering. 214 </b> 215 <p> 216 This method configures a database, not only operations performed using 217 the specified {@link com.sleepycat.db.Database Database} handle. 218 <p> 219 This method may not be called after the database is opened. 220 If the database already exists when it is opened, 221 the information specified to this method will be ignored. 222 If creating additional databases in a single physical file, information 223 specified to this method will be ignored and the byte order of the 224 existing databases will be used. 225 <p> 226 @param byteOrder 227 The byte order as an integer; for example, big endian order is the 228 number 4,321, and little endian order is the number 1,234. 229 */ setByteOrder(final int byteOrder)230 public void setByteOrder(final int byteOrder) { 231 this.byteOrder = byteOrder; 232 } 233 234 /** 235 Return the database byte order; a byte order of 4,321 indicates a 236 big endian order, and a byte order of 1,234 indicates a little 237 endian order. 238 <p> 239 This method may be called at any time during the life of the application. 240 <p> 241 @return 242 The database byte order; a byte order of 4,321 indicates a 243 big endian order, and a byte order of 1,234 indicates a little 244 endian order. 245 */ getByteOrder()246 public int getByteOrder() { 247 return byteOrder; 248 } 249 250 /** 251 Return if the underlying database files were created on an architecture 252 of the same byte order as the current one. 253 <p> 254 This information may be used to determine whether application data 255 needs to be adjusted for this architecture or not. 256 <p> 257 This method may not be called before the 258 database has been opened. 259 <p> 260 @return 261 Return false if the underlying database files were created on an 262 architecture of the same byte order as the current one, and true if 263 they were not (that is, big-endian on a little-endian machine, or 264 vice versa). 265 */ getByteSwapped()266 public boolean getByteSwapped() { 267 return byteOrder != 0 && byteOrder != DbUtil.default_lorder(); 268 } 269 270 /** 271 Set the Btree compression callbacks. 272 */ setBtreeCompressor(final BtreeCompressor btreeCompressor)273 public void setBtreeCompressor(final BtreeCompressor btreeCompressor) { 274 this.btreeCompressor = btreeCompressor; 275 } 276 277 /** 278 Get the Btree compression callbacks. 279 */ getBtreeCompressor()280 public BtreeCompressor getBtreeCompressor() { 281 return btreeCompressor; 282 } 283 284 /** 285 Set the Btree prefix callback. The prefix callback is used to determine 286 the amount by which keys stored on the Btree internal pages can be 287 safely truncated without losing their uniqueness. See the 288 <a href="{@docRoot}/../programmer_reference/bt_conf.html#am_conf_bt_prefix" target="_top">Btree prefix 289 comparison</a> section of the Berkeley DB Reference Guide for more 290 details about how this works. The usefulness of this is data-dependent, 291 but can produce significantly reduced tree sizes and search times in 292 some data sets. 293 <p> 294 If no prefix callback or key comparison callback is specified by the 295 application, a default lexical comparison function is used to calculate 296 prefixes. If no prefix callback is specified and a key comparison 297 callback is specified, no prefix function is used. It is an error to 298 specify a prefix function without also specifying a Btree key comparison 299 function. 300 */ setBtreePrefixCalculator( final BtreePrefixCalculator btreePrefixCalculator)301 public void setBtreePrefixCalculator( 302 final BtreePrefixCalculator btreePrefixCalculator) { 303 this.btreePrefixCalculator = btreePrefixCalculator; 304 } 305 306 /** 307 Return the Btree prefix callback. 308 <p> 309 This method may be called at any time during the life of the application. 310 <p> 311 @return 312 The Btree prefix callback. 313 */ getBtreePrefixCalculator()314 public BtreePrefixCalculator getBtreePrefixCalculator() { 315 return btreePrefixCalculator; 316 } 317 318 /** 319 Set the size of the shared memory buffer pool, that is, the size of the 320 cache. 321 <p> 322 The cache should be the size of the normal working data set of the 323 application, with some small amount of additional memory for unusual 324 situations. (Note: the working set is not the same as the number of 325 pages accessed simultaneously, and is usually much larger.) 326 <p> 327 The default cache size is 256KB, and may not be specified as less than 328 20KB. Any cache size less than 500MB is automatically increased by 25% 329 to account for buffer pool overhead; cache sizes larger than 500MB are 330 used as specified. The current maximum size of a single cache is 4GB. 331 (All sizes are in powers-of-two, that is, 256KB is 2^18 not 256,000.) 332 <p> 333 Because databases opened within database environments use the cache 334 specified to the environment, it is an error to attempt to configure a 335 cache size in a database created within an environment. 336 <p> 337 This method may not be called after the database is opened. 338 <p> 339 This method may be called at any time during the life of the application. 340 <p> 341 @param cacheSize 342 The size of the shared memory buffer pool, that is, the size of the 343 cache. 344 <p> 345 <p> 346 @throws DatabaseException if a failure occurs. 347 */ setCacheSize(final long cacheSize)348 public void setCacheSize(final long cacheSize) { 349 this.cacheSize = cacheSize; 350 } 351 352 /** 353 Return the size of the shared memory buffer pool, that is, the cache. 354 <p> 355 This method may be called at any time during the life of the application. 356 <p> 357 @return 358 The size of the shared memory buffer pool, that is, the cache. 359 */ getCacheSize()360 public long getCacheSize() { 361 return cacheSize; 362 } 363 364 /** 365 Specify which directory a database should be created in or looked for. 366 <p> 367 @param createDir 368 The directory will be used to create or locate the database file specified in 369 the openDatabase method call. The directory must be one of the directories 370 in the environment list specified by EnvironmentConfig.addDataDirectory. 371 <p> 372 <p> 373 @throws DatabaseException if a failure occurs. 374 */ setCreateDir(final java.io.File createDir)375 public void setCreateDir(final java.io.File createDir) { 376 this.createDir = createDir; 377 } 378 379 /** 380 Return the directory a database will/has been created in or looked for. 381 <p> 382 This method may be called at any time during the life of the application. 383 <p> 384 @return 385 The directory a database will/has been created in or looked for. 386 */ getCreateDir()387 public java.io.File getCreateDir() { 388 return this.createDir; 389 } 390 391 /** 392 Set the number of shared memory buffer pools, that is, the number of 393 caches. 394 <p> 395 It is possible to specify caches larger than 4GB and/or large enough 396 they cannot be allocated contiguously on some architectures. For 397 example, some releases of Solaris limit the amount of memory that may 398 be allocated contiguously by a process. This method allows applications 399 to break the cache broken up into a number of equally sized, separate 400 pieces of memory. 401 <p> 402 <p> 403 Because databases opened within database environments use the cache 404 specified to the environment, it is an error to attempt to configure 405 multiple caches in a database created within an environment. 406 <p> 407 This method may not be called after the database is opened. 408 <p> 409 This method may be called at any time during the life of the application. 410 <p> 411 @param cacheCount 412 The number of shared memory buffer pools, that is, the number of caches. 413 <p> 414 <p> 415 @throws DatabaseException if a failure occurs. 416 */ setCacheCount(final int cacheCount)417 public void setCacheCount(final int cacheCount) { 418 this.cacheCount = cacheCount; 419 } 420 421 /** 422 Return the number of shared memory buffer pools, that is, the number 423 of caches. 424 <p> 425 This method may be called at any time during the life of the application. 426 <p> 427 @return 428 The number of shared memory buffer pools, that is, the number 429 of caches. 430 */ getCacheCount()431 public int getCacheCount() { 432 return cacheCount; 433 } 434 435 /** 436 Configure the database environment to do checksum verification of 437 pages read into the cache from the backing filestore. 438 <p> 439 Berkeley DB uses the SHA1 Secure Hash Algorithm if encryption is 440 also configured for this database, and a general hash algorithm if 441 it is not. 442 <p> 443 Calling this method only affects the specified {@link com.sleepycat.db.Database Database} handle 444 (and any other library handles opened within the scope of that handle). 445 <p> 446 If the database already exists when the database is opened, any database 447 configuration specified by this method 448 will be ignored. 449 If creating additional databases in a file, the checksum behavior 450 specified must be consistent with the existing databases in the file or 451 an error will be returned. 452 <p> 453 @param checksum 454 If true, configure the database environment to do checksum verification 455 of pages read into the cache from the backing filestore. 456 A value of false is illegal to this method, that is, once set, the 457 configuration cannot be cleared. 458 */ setChecksum(final boolean checksum)459 public void setChecksum(final boolean checksum) { 460 this.checksum = checksum; 461 } 462 463 /** 464 Return true if the database environment is configured to do checksum 465 verification of pages read into the cache from the backing 466 filestore. 467 <p> 468 This method may be called at any time during the life of the application. 469 <p> 470 @return 471 True if the database environment is configured to do checksum 472 verification of pages read into the cache from the backing 473 filestore. 474 */ getChecksum()475 public boolean getChecksum() { 476 return checksum; 477 } 478 479 /** 480 Configure the database to support read uncommitted. 481 <p> 482 Read operations on the database may request the return of modified 483 but not yet committed data. This flag must be specified on all 484 {@link com.sleepycat.db.Database Database} handles used to perform read uncommitted or database 485 updates, otherwise requests for read uncommitted may not be honored and 486 the read may block. 487 <p> 488 @param readUncommitted 489 If true, configure the database to support read uncommitted. 490 */ setReadUncommitted(final boolean readUncommitted)491 public void setReadUncommitted(final boolean readUncommitted) { 492 this.readUncommitted = readUncommitted; 493 } 494 495 /** 496 Return true if the database is configured to support read uncommitted. 497 <p> 498 This method may be called at any time during the life of the application. 499 <p> 500 @return 501 True if the database is configured to support read uncommitted. 502 */ getReadUncommitted()503 public boolean getReadUncommitted() { 504 return readUncommitted; 505 } 506 507 /** 508 Configure the database to support read uncommitted. 509 <p> 510 Read operations on the database may request the return of modified 511 but not yet committed data. This flag must be specified on all 512 {@link com.sleepycat.db.Database Database} handles used to perform read uncommitted or database 513 updates, otherwise requests for read uncommitted may not be honored and 514 the read may block. 515 <p> 516 @param dirtyRead 517 If true, configure the database to support read uncommitted. 518 <p> 519 @deprecated This has been replaced by {@link #setReadUncommitted} to conform to ANSI 520 database isolation terminology. 521 */ setDirtyRead(final boolean dirtyRead)522 public void setDirtyRead(final boolean dirtyRead) { 523 setReadUncommitted(dirtyRead); 524 } 525 526 /** 527 Return true if the database is configured to support read uncommitted. 528 <p> 529 This method may be called at any time during the life of the application. 530 <p> 531 @return 532 True if the database is configured to support read uncommitted. 533 <p> 534 @deprecated This has been replaced by {@link #getReadUncommitted} to conform to ANSI 535 database isolation terminology. 536 */ getDirtyRead()537 public boolean getDirtyRead() { 538 return getReadUncommitted(); 539 } 540 541 /** 542 Set the duplicate data item comparison callback. The comparison 543 function is called whenever it is necessary to compare a data item 544 specified by the application with a data item currently stored in the 545 database. This comparator is only used if 546 {@link com.sleepycat.db.DatabaseConfig#setSortedDuplicates DatabaseConfig.setSortedDuplicates} is also configured. 547 <p> 548 If no comparison function is specified, the data items are compared 549 lexically, with shorter data items collating before longer data items. 550 <p> 551 The <code>compare</code> method is passed the byte arrays representing 552 data items in the database. If you know how your data is organized in 553 the byte array, then you can write a comparison routine that directly 554 examines the contents of the arrays. Otherwise, you have to 555 reconstruct your original objects, and then perform the comparison. 556 <p> 557 @param duplicateComparator 558 the comparison callback for duplicate data items. 559 */ setDuplicateComparator( final java.util.Comparator duplicateComparator)560 public void setDuplicateComparator( 561 final java.util.Comparator duplicateComparator) { 562 this.duplicateComparator = duplicateComparator; 563 } 564 565 /** 566 Return the duplicate data item comparison callback. 567 <p> 568 @return the duplicate data item Comparator, or null if the default Comparator 569 will be used. 570 */ getDuplicateComparator()571 public java.util.Comparator getDuplicateComparator() { 572 return duplicateComparator; 573 } 574 575 /** 576 Set the password used to perform encryption and decryption. 577 <p> 578 Because databases opened within environments use the password 579 specified to the environment, it is an error to attempt to set a 580 password in a database created within an environment. 581 <p> 582 Berkeley DB uses the Rijndael/AES (also known as the Advanced 583 Encryption Standard and Federal Information Processing 584 Standard (FIPS) 197) algorithm for encryption or decryption. 585 */ setEncrypted(final String password)586 public void setEncrypted(final String password) { 587 this.password = password; 588 } 589 590 /** 591 Return true if the database has been configured to perform encryption. 592 <p> 593 This method may be called at any time during the life of the application. 594 <p> 595 @return 596 True if the database has been configured to perform encryption. 597 */ getEncrypted()598 public boolean getEncrypted() { 599 return (password != null); 600 } 601 602 /** 603 Set the function to be called if an error occurs. 604 <p> 605 When an error occurs in the Berkeley DB library, an exception is thrown. 606 In some cases, however, the error information returned to the 607 application may be insufficient to completely describe the cause of the 608 error, especially during initial application debugging. 609 <p> 610 The {@link com.sleepycat.db.EnvironmentConfig#setErrorHandler EnvironmentConfig.setErrorHandler} and {@link com.sleepycat.db.DatabaseConfig#setErrorHandler DatabaseConfig.setErrorHandler} methods are used to enhance the mechanism for reporting 611 error messages to the application. In some cases, when an error occurs, 612 Berkeley DB will invoke the ErrorHandler's object error method. It is 613 up to this method to display the error message in an appropriate manner. 614 <p> 615 Alternatively, applications can use {@link com.sleepycat.db.EnvironmentConfig#setErrorStream EnvironmentConfig.setErrorStream} and {@link com.sleepycat.db.DatabaseConfig#setErrorStream DatabaseConfig.setErrorStream} to 616 display the additional information via an output stream. Applications 617 should not mix these approaches. 618 <p> 619 This error-logging enhancement does not slow performance or significantly 620 increase application size, and may be run during normal operation as well 621 as during application debugging. 622 <p> 623 For {@link com.sleepycat.db.Database Database} handles opened inside of database environments, 624 calling this method affects the entire environment and is equivalent to 625 calling {@link com.sleepycat.db.EnvironmentConfig#setErrorHandler EnvironmentConfig.setErrorHandler}. 626 <p> 627 This method may be called at any time during the life of the application. 628 <p> 629 @param errorHandler 630 The function to be called if an error occurs. 631 */ setErrorHandler(final ErrorHandler errorHandler)632 public void setErrorHandler(final ErrorHandler errorHandler) { 633 this.errorHandler = errorHandler; 634 } 635 636 /** 637 Return the function to be called if an error occurs. 638 <p> 639 This method may be called at any time during the life of the application. 640 <p> 641 @return 642 The function to be called if an error occurs. 643 */ getErrorHandler()644 public ErrorHandler getErrorHandler() { 645 return errorHandler; 646 } 647 648 /** 649 Set the prefix string that appears before error messages. 650 <p> 651 For {@link com.sleepycat.db.Database Database} handles opened inside of database environments, 652 calling this method affects the entire environment and is equivalent to 653 calling {@link com.sleepycat.db.EnvironmentConfig#setErrorPrefix EnvironmentConfig.setErrorPrefix}. 654 <p> 655 This method may be called at any time during the life of the application. 656 <p> 657 @param errorPrefix 658 The prefix string that appears before error messages. 659 */ setErrorPrefix(final String errorPrefix)660 public void setErrorPrefix(final String errorPrefix) { 661 this.errorPrefix = errorPrefix; 662 } 663 664 /** 665 Return the prefix string that appears before error messages. 666 <p> 667 This method may be called at any time during the life of the application. 668 <p> 669 @return 670 The prefix string that appears before error messages. 671 */ getErrorPrefix()672 public String getErrorPrefix() { 673 return errorPrefix; 674 } 675 676 /** 677 Set an OutputStream for displaying error messages. 678 <p> 679 When an error occurs in the Berkeley DB library, an exception is thrown. 680 In some cases, however, the error information returned to the 681 application may be insufficient to completely describe the cause of the 682 error, especially during initial application debugging. 683 <p> 684 The {@link com.sleepycat.db.EnvironmentConfig#setErrorStream EnvironmentConfig.setErrorStream} and 685 {@link com.sleepycat.db.DatabaseConfig#setErrorStream DatabaseConfig.setErrorStream} methods are used to enhance 686 the mechanism for reporting error messages to the application by setting 687 a OutputStream to be used for displaying additional Berkeley DB error 688 messages. In some cases, when an error occurs, Berkeley DB will output 689 an additional error message to the specified stream. 690 <p> 691 The error message will consist of the prefix string and a colon 692 ("<b>:</b>") (if a prefix string was previously specified using 693 {@link com.sleepycat.db.EnvironmentConfig#setErrorPrefix EnvironmentConfig.setErrorPrefix} or {@link com.sleepycat.db.DatabaseConfig#setErrorPrefix DatabaseConfig.setErrorPrefix}), an error string, and a trailing newline character. 694 <p> 695 Setting errorStream to null unconfigures the interface. 696 <p> 697 Alternatively, applications can use {@link com.sleepycat.db.EnvironmentConfig#setErrorHandler EnvironmentConfig.setErrorHandler} and {@link com.sleepycat.db.DatabaseConfig#setErrorHandler DatabaseConfig.setErrorHandler} to capture 698 the additional error information in a way that does not use output 699 streams. Applications should not mix these approaches. 700 <p> 701 This error-logging enhancement does not slow performance or significantly 702 increase application size, and may be run during normal operation as well 703 as during application debugging. 704 <p> 705 This method may be called at any time during the life of the application. 706 <p> 707 @param errorStream 708 The application-specified OutputStream for error messages. 709 */ setErrorStream(final java.io.OutputStream errorStream)710 public void setErrorStream(final java.io.OutputStream errorStream) { 711 this.errorStream = errorStream; 712 } 713 714 /** 715 Return the an OutputStream for displaying error messages. 716 <p> 717 This method may be called at any time during the life of the application. 718 <p> 719 @return 720 The an OutputStream for displaying error messages. 721 */ getErrorStream()722 public java.io.OutputStream getErrorStream() { 723 return errorStream; 724 } 725 726 /** 727 Configure the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method to fail if 728 the database already exists. 729 <p> 730 The exclusiveCreate mode is only meaningful if specified with the 731 allowCreate mode. 732 <p> 733 @param exclusiveCreate 734 If true, configure the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method to 735 fail if the database already exists. 736 */ setExclusiveCreate(final boolean exclusiveCreate)737 public void setExclusiveCreate(final boolean exclusiveCreate) { 738 this.exclusiveCreate = exclusiveCreate; 739 } 740 741 /** 742 Return true if the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method is configured 743 to fail if the database already exists. 744 <p> 745 This method may be called at any time during the life of the application. 746 <p> 747 @return 748 True if the {@link com.sleepycat.db.Environment#openDatabase Environment.openDatabase} method is configured 749 to fail if the database already exists. 750 */ getExclusiveCreate()751 public boolean getExclusiveCreate() { 752 return exclusiveCreate; 753 } 754 755 /** 756 Set an object whose methods are called to provide feedback. 757 <p> 758 Some operations performed by the Berkeley DB library can take 759 non-trivial amounts of time. This method can be used by applications 760 to monitor progress within these operations. When an operation is 761 likely to take a long time, Berkeley DB will call the object's methods 762 with progress information. 763 <p> 764 It is up to the object's methods to display this information in an 765 appropriate manner. 766 <p> 767 This method configures only operations performed using a single a 768 {@link com.sleepycat.db.Environment Environment} handle 769 <p> 770 This method may be called at any time during the life of the application. 771 <p> 772 @param feedbackHandler 773 An object whose methods are called to provide feedback. 774 */ setFeedbackHandler(final FeedbackHandler feedbackHandler)775 public void setFeedbackHandler(final FeedbackHandler feedbackHandler) { 776 this.feedbackHandler = feedbackHandler; 777 } 778 779 /** 780 Return the object's methods to be called to provide feedback. 781 <p> 782 This method may be called at any time during the life of the application. 783 <p> 784 @return 785 The object's methods to be called to provide feedback. 786 */ getFeedbackHandler()787 public FeedbackHandler getFeedbackHandler() { 788 return feedbackHandler; 789 } 790 791 /** 792 Set the desired density within the hash table. 793 <p> 794 If no value is specified, the fill factor will be selected dynamically 795 as pages are filled. 796 <p> 797 The density is an approximation of the number of keys allowed to 798 accumulate in any one bucket, determining when the hash table grows or 799 shrinks. If you know the average sizes of the keys and data in your 800 data set, setting the fill factor can enhance performance. A reasonable 801 rule computing fill factor is to set it to the following: 802 <blockquote><pre> 803 (pagesize - 32) / (average_key_size + average_data_size + 8) 804 </pre></blockquote> 805 <p> 806 This method configures a database, not only operations performed using 807 the specified {@link com.sleepycat.db.Database Database} handle. 808 <p> 809 This method may not be called after the database is opened. 810 If the database already exists when it is opened, 811 the information specified to this method will be ignored. 812 <p> 813 @param hashFillFactor 814 The desired density within the hash table. 815 */ setHashFillFactor(final int hashFillFactor)816 public void setHashFillFactor(final int hashFillFactor) { 817 this.hashFillFactor = hashFillFactor; 818 } 819 820 /** 821 Return the hash table density. 822 <p> 823 This method may be called at any time during the life of the application. 824 <p> 825 @return 826 The hash table density. 827 */ getHashFillFactor()828 public int getHashFillFactor() { 829 return hashFillFactor; 830 } 831 832 /** 833 Set the Hash key comparison function. The comparison function is called 834 whenever it is necessary to compare a key specified by the application with 835 a key currently stored in the database. 836 <p> 837 If no comparison function is specified, a byte-by-byte comparison is 838 performed. 839 <p> 840 The <code>compare</code> method is passed the byte arrays representing 841 keys that are stored in the database. If you know how your data is 842 organized in the byte array, then you can write a comparison routine that 843 directly examines the contents of the arrays. Otherwise, you have to 844 reconstruct your original objects, and then perform the comparison. 845 */ setHashComparator(final java.util.Comparator hashComparator)846 public void setHashComparator(final java.util.Comparator hashComparator) { 847 this.hashComparator = hashComparator; 848 } 849 850 /** 851 Return the Comparator used to compare keys in a Hash database. 852 <p> 853 This method may be called at any time during the life of the application. 854 <p> 855 @return 856 The Comparator used to compare keys in a Hash database. 857 */ getHashComparator()858 public java.util.Comparator getHashComparator() { 859 return hashComparator; 860 } 861 862 /** 863 Set a database-specific hash function. 864 <p> 865 If no hash function is specified, a default hash function is used. 866 Because no hash function performs equally well on all possible data, 867 the user may find that the built-in hash function performs poorly 868 with a particular data set. 869 <p> 870 This method configures operations performed using the specified 871 {@link com.sleepycat.db.Database Database} object, not all operations performed on the underlying 872 database. 873 <p> 874 This method may not be called after the database is opened. 875 If the database already exists when it is opened, 876 the information specified to this method must be the same as that 877 historically used to create the database or corruption can occur. 878 <p> 879 @param hasher 880 A database-specific hash function. 881 */ setHasher(final Hasher hasher)882 public void setHasher(final Hasher hasher) { 883 this.hasher = hasher; 884 } 885 886 /** 887 Return the database-specific hash function. 888 <p> 889 This method may be called at any time during the life of the application. 890 <p> 891 @return 892 The database-specific hash function. 893 */ getHasher()894 public Hasher getHasher() { 895 return hasher; 896 } 897 898 /** 899 Set an estimate of the final size of the hash table. 900 <p> 901 In order for the estimate to be used when creating the database, the 902 {@link com.sleepycat.db.DatabaseConfig#setHashFillFactor DatabaseConfig.setHashFillFactor} method must also be called. 903 If the estimate or fill factor are not set or are set too low, hash 904 tables will still expand gracefully as keys are entered, although a 905 slight performance degradation may be noticed. 906 <p> 907 This method configures a database, not only operations performed using 908 the specified {@link com.sleepycat.db.Database Database} handle. 909 <p> 910 This method may not be called after the database is opened. 911 If the database already exists when it is opened, 912 the information specified to this method will be ignored. 913 <p> 914 @param hashNumElements 915 An estimate of the final size of the hash table. 916 */ setHashNumElements(final int hashNumElements)917 public void setHashNumElements(final int hashNumElements) { 918 this.hashNumElements = hashNumElements; 919 } 920 921 /** 922 Return the estimate of the final size of the hash table. 923 <p> 924 This method may be called at any time during the life of the application. 925 <p> 926 @return 927 The estimate of the final size of the hash table. 928 */ getHashNumElements()929 public int getHashNumElements() { 930 return hashNumElements; 931 } 932 933 /** 934 Set the maximum on-disk database file size used by a database configured to 935 use the Heap access method. If this method is never called, the database's 936 file size can grow without bound. If this method is called, then the heap 937 file can never grow larger than the limit defined by this method. In that 938 case, attempts to update or create records in a Heap database that has 939 reached its maximum size will throw a {@link com.sleepycat.db.HeapFullException HeapFullException}. 940 <p> 941 The size specified to this method must be at least three times the database 942 page size. That is, a Heap database must contain at least three database 943 pages. You can set the database page size using {@link #setPageSize}. 944 <p> 945 This method may not be called after the database is opened. Further, if this 946 method is called on an existing Heap database, the size specified here must 947 match the size used to create the database. Note, however, that specifying 948 an incorrect size to this method will not result in an error return until 949 the database is opened. 950 <p> 951 @param bytes 952 The maximum on-disk database file size. 953 954 */ setHeapsize(final long bytes)955 public void setHeapsize(final long bytes) { 956 this.heapSize = bytes; 957 } 958 959 /** 960 Return the maximum on-disk database file size. 961 <p> 962 This method may be called at any time during the life of the application. 963 <p> 964 @return 965 The maximum on-disk database file size. 966 */ getHeapsize()967 public long getHeapsize() { 968 return heapSize; 969 } 970 971 /** 972 Sets the number of pages in a region of a database configured to use 973 the Heap access method. If this method is never called, the default region 974 size for the database's page size will be used. You can set the database 975 page size using {@link #setPageSize}. 976 <p> 977 This method may not be called after the database is opened. Further, if this 978 method is called on an existing Heap database, the value specified here will 979 be ignored. If the specified region size is larger than the maximum region 980 size for the database's page size, an error will be returned when the 981 database is opened. The maximum allowable region size will be included in 982 the error message. 983 @param npages 984 The size of the region, in pages. 985 */ setHeapRegionSize(final int npages)986 public void setHeapRegionSize(final int npages) { 987 this.heapRegionSize = npages; 988 } 989 990 /** 991 Return the number of pages in a region of the database. 992 <p> 993 This method may be called at any time during the life of the application. 994 <p> 995 @return 996 The size of the region, in pages. 997 */ getHeapRegionSize()998 public long getHeapRegionSize() { 999 return heapRegionSize; 1000 } 1001 1002 /** 1003 Set a function to be called with an informational message. 1004 <p> 1005 There are interfaces in the Berkeley DB library which either directly 1006 output informational messages or statistical information, or configure 1007 the library to output such messages when performing other operations, 1008 {@link com.sleepycat.db.EnvironmentConfig#setVerboseDeadlock EnvironmentConfig.setVerboseDeadlock} for example. 1009 <p> 1010 The {@link com.sleepycat.db.EnvironmentConfig#setMessageHandler EnvironmentConfig.setMessageHandler} and 1011 {@link com.sleepycat.db.DatabaseConfig#setMessageHandler DatabaseConfig.setMessageHandler} methods are used to display 1012 these messages for the application. 1013 <p> 1014 Setting messageHandler to null unconfigures the interface. 1015 <p> 1016 Alternatively, you can use {@link com.sleepycat.db.EnvironmentConfig#setMessageStream EnvironmentConfig.setMessageStream} 1017 and {@link com.sleepycat.db.DatabaseConfig#setMessageStream DatabaseConfig.setMessageStream} to send the additional 1018 information directly to an output streams. You should not mix these 1019 approaches. 1020 <p> 1021 For {@link com.sleepycat.db.Database Database} handles opened inside of database environments, 1022 calling this method affects the entire environment and is equivalent to 1023 calling {@link com.sleepycat.db.EnvironmentConfig#setMessageHandler EnvironmentConfig.setMessageHandler}. 1024 <p> 1025 This method may be called at any time during the life of the application. 1026 <p> 1027 @param messageHandler 1028 The application-specified function for informational messages. 1029 */ setMessageHandler(final MessageHandler messageHandler)1030 public void setMessageHandler(final MessageHandler messageHandler) { 1031 this.messageHandler = messageHandler; 1032 } 1033 1034 /** 1035 Return the function to be called with an informational message. 1036 <p> 1037 This method may be called at any time during the life of the application. 1038 <p> 1039 @return 1040 The function to be called with an informational message. 1041 */ getMessageHandler()1042 public MessageHandler getMessageHandler() { 1043 return messageHandler; 1044 } 1045 1046 /** 1047 Set an OutputStream for displaying informational messages. 1048 <p> 1049 There are interfaces in the Berkeley DB library which either directly 1050 output informational messages or statistical information, or configure 1051 the library to output such messages when performing other operations, 1052 {@link com.sleepycat.db.EnvironmentConfig#setVerboseDeadlock EnvironmentConfig.setVerboseDeadlock} for example. 1053 <p> 1054 The {@link com.sleepycat.db.EnvironmentConfig#setMessageStream EnvironmentConfig.setMessageStream} and 1055 {@link com.sleepycat.db.DatabaseConfig#setMessageStream DatabaseConfig.setMessageStream} methods are used to display 1056 these messages for the application. In this case, the message will 1057 include a trailing newline character. 1058 <p> 1059 Setting messageStream to null unconfigures the interface. 1060 <p> 1061 Alternatively, you can use {@link com.sleepycat.db.EnvironmentConfig#setMessageHandler EnvironmentConfig.setMessageHandler} 1062 and {@link com.sleepycat.db.DatabaseConfig#setMessageHandler DatabaseConfig.setMessageHandler} to capture the additional 1063 information in a way that does not use output streams. You should not 1064 mix these approaches. 1065 <p> 1066 For {@link com.sleepycat.db.Database Database} handles opened inside of database environments, 1067 calling this method affects the entire environment and is equivalent to 1068 calling {@link com.sleepycat.db.EnvironmentConfig#setMessageStream EnvironmentConfig.setMessageStream}. 1069 <p> 1070 This method may be called at any time during the life of the application. 1071 <p> 1072 @param messageStream 1073 The application-specified OutputStream for informational messages. 1074 */ setMessageStream(final java.io.OutputStream messageStream)1075 public void setMessageStream(final java.io.OutputStream messageStream) { 1076 this.messageStream = messageStream; 1077 } 1078 1079 /** 1080 Return the an OutputStream for displaying informational messages. 1081 <p> 1082 This method may be called at any time during the life of the application. 1083 <p> 1084 @return 1085 The an OutputStream for displaying informational messages. 1086 */ getMessageStream()1087 public java.io.OutputStream getMessageStream() { 1088 return messageStream; 1089 } 1090 1091 /** 1092 On UNIX systems or in IEEE/ANSI Std 1003.1 (POSIX) environments, files 1093 created by the database open are created with mode <code>mode</code> 1094 (as described in the <code>chmod</code>(2) manual page) and modified 1095 by the process' umask value at the time of creation (see the 1096 <code>umask</code>(2) manual page). Created files are owned by the 1097 process owner; the group ownership of created files is based on the 1098 system and directory defaults, and is not further specified by Berkeley 1099 DB. System shared memory segments created by the database open are 1100 created with mode <code>mode</code>, unmodified by the process' umask 1101 value. If <code>mode</code> is 0, the database open will use a default 1102 mode of readable and writable by both owner and group. 1103 <p> 1104 On Windows systems, the mode parameter is ignored. 1105 <p> 1106 @param mode 1107 the mode used to create files 1108 */ setMode(final int mode)1109 public void setMode(final int mode) { 1110 this.mode = mode; 1111 } 1112 1113 /** 1114 Return the mode used to create files. 1115 <p> 1116 This method may be called at any time during the life of the application. 1117 <p> 1118 @return 1119 The mode used to create files. 1120 */ getMode()1121 public long getMode() { 1122 return mode; 1123 } 1124 1125 /** 1126 Configured the database with support for multiversion concurrency control. 1127 This will cause updates to the database to follow a copy-on-write 1128 protocol, which is required to support Snapshot Isolation. See 1129 {@link TransactionConfig#setSnapshot}) for more information. 1130 Multiversion access requires that the database be opened 1131 in a transaction and is not supported for queue databases. 1132 <p> 1133 @param multiversion 1134 If true, configure the database with support for multiversion concurrency 1135 control. 1136 */ setMultiversion(final boolean multiversion)1137 public void setMultiversion(final boolean multiversion) { 1138 this.multiversion = multiversion; 1139 } 1140 1141 /** 1142 Return true if the database is configured for multiversion concurrency control. 1143 <p> 1144 This method may be called at any time during the life of the application. 1145 <p> 1146 @return 1147 True if the database is configured for multiversion concurrency control. 1148 */ getMultiversion()1149 public boolean getMultiversion() { 1150 return multiversion; 1151 } 1152 1153 /** 1154 Configure the library to not map this database into memory. 1155 <p> 1156 @param noMMap 1157 If true, configure the library to not map this database into memory. 1158 */ setNoMMap(final boolean noMMap)1159 public void setNoMMap(final boolean noMMap) { 1160 this.noMMap = noMMap; 1161 } 1162 1163 /** 1164 Return true if the library is configured to not map this database into 1165 memory. 1166 <p> 1167 This method may be called at any time during the life of the application. 1168 <p> 1169 @return 1170 True if the library is configured to not map this database into 1171 memory. 1172 */ getNoMMap()1173 public boolean getNoMMap() { 1174 return noMMap; 1175 } 1176 1177 /** 1178 Configure the {@link com.sleepycat.db.Database Database} handle to obtain a 1179 write lock on the entire database. 1180 <p> 1181 This method may not be called after the database is opened. 1182 <p> 1183 @param noWaitDbExclLock 1184 If True, configure the {@link com.sleepycat.db.Database Database} handle to 1185 obtain a write lock on the entire database. When the database is opened it will 1186 immediately throw 1187 {@link com.sleepycat.db.LockNotGrantedException LockNotGrantedException} if it 1188 cannot obtain the exclusive lock immediately. If False, configure the 1189 {@link com.sleepycat.db.Database Database} handle to obtain a write lock on the 1190 entire database. When the database is opened, it will block until it can obtain 1191 the exclusive lock. If null, do not configure the 1192 {@link com.sleepycat.db.Database Database} handle to obtain a write lock on the 1193 entire database. 1194 <p> 1195 Handles configured for a write lock on the entire database can only have one 1196 active transaction at a time. 1197 */ setNoWaitDbExclusiveLock(Boolean noWaitDbExclLock)1198 public void setNoWaitDbExclusiveLock(Boolean noWaitDbExclLock) { 1199 this.noWaitDbExclusiveLock = noWaitDbExclLock; 1200 } 1201 1202 /** 1203 Return whether the {@link com.sleepycat.db.Database Database} handle is 1204 configured to obtain a write lock on the entire database. 1205 <p> 1206 This method may be called at any time during the life of the application. 1207 <p> 1208 @return 1209 True if the {@link com.sleepycat.db.Database Database} handle is configured for 1210 immediate exclusive database locking. In this case, the locking operation will 1211 error out if it cannot immediately obtain an exclusive lock. False if the 1212 {@link com.sleepycat.db.Database Database} handle is configured for exclusive 1213 database locking. In this case, it will block until it can obtain the exclusive 1214 database lock when database is opened. Null if the 1215 {@link com.sleepycat.db.Database Database} handle is not configured for 1216 exclusive locking. 1217 */ getNoWaitDbExclusiveLock()1218 public Boolean getNoWaitDbExclusiveLock() { 1219 return noWaitDbExclusiveLock; 1220 } 1221 1222 /** 1223 Set the size of the pages used to hold items in the database, in bytes. 1224 <p> 1225 The minimum page size is 512 bytes, the maximum page size is 64K bytes, 1226 and the page size must be a power-of-two. If the page size is not 1227 explicitly set, one is selected based on the underlying filesystem I/O 1228 block size. The automatically selected size has a lower limit of 512 1229 bytes and an upper limit of 16K bytes. 1230 <p> 1231 This method configures a database, not only operations performed using 1232 the specified {@link com.sleepycat.db.Database Database} handle. 1233 <p> 1234 This method may not be called after the database is opened. 1235 If the database already exists when it is opened, 1236 the information specified to this method will be ignored. 1237 If creating additional databases in a file, the page size specified must 1238 be consistent with the existing databases in the file or an error will 1239 be returned. 1240 <p> 1241 @param pageSize 1242 The size of the pages used to hold items in the database, in bytes. 1243 */ setPageSize(final int pageSize)1244 public void setPageSize(final int pageSize) { 1245 this.pageSize = pageSize; 1246 } 1247 1248 /** 1249 Return the size of the pages used to hold items in the database, in bytes. 1250 <p> 1251 This method may be called at any time during the life of the application. 1252 <p> 1253 @return 1254 The size of the pages used to hold items in the database, in bytes. 1255 */ getPageSize()1256 public int getPageSize() { 1257 return pageSize; 1258 } 1259 1260 /** 1261 Set the function to be called if the database environment panics. 1262 <p> 1263 Errors can occur in the Berkeley DB library where the only solution is 1264 to shut down the application and run recovery (for example, if Berkeley 1265 DB is unable to allocate heap memory). In such cases, the Berkeley DB 1266 methods will throw a {@link com.sleepycat.db.RunRecoveryException RunRecoveryException}. It is often easier 1267 to simply exit the application when such errors occur rather than 1268 gracefully return up the stack. This method specifies a function to be 1269 called when {@link com.sleepycat.db.RunRecoveryException RunRecoveryException} is about to be thrown from a 1270 Berkeley DB method. 1271 <p> 1272 For {@link com.sleepycat.db.Database Database} handles opened inside of database environments, 1273 calling this method affects the entire environment and is equivalent to 1274 calling {@link com.sleepycat.db.EnvironmentConfig#setPanicHandler EnvironmentConfig.setPanicHandler}. 1275 <p> 1276 This method may be called at any time during the life of the application. 1277 <p> 1278 @param panicHandler 1279 The function to be called if the database environment panics. 1280 */ setPanicHandler(final PanicHandler panicHandler)1281 public void setPanicHandler(final PanicHandler panicHandler) { 1282 this.panicHandler = panicHandler; 1283 } 1284 1285 /** 1286 Return the function to be called if the database environment panics. 1287 <p> 1288 This method may be called at any time during the life of the application. 1289 <p> 1290 @return 1291 The function to be called if the database environment panics. 1292 */ getPanicHandler()1293 public PanicHandler getPanicHandler() { 1294 return panicHandler; 1295 } 1296 1297 /** 1298 Enable or disable database partitioning, and set the callback that will 1299 be used for the partitioning. 1300 <p> 1301 This method may only be called before opening a database. 1302 <p> 1303 @param parts 1304 The number of partitions that will be created. 1305 <p> 1306 @param partitionHandler 1307 The function to be called to determine which partition a key resides in. 1308 */ setPartitionByCallback(int parts, final PartitionHandler partitionHandler)1309 public void setPartitionByCallback(int parts, 1310 final PartitionHandler partitionHandler) { 1311 this.partitionParts = parts; 1312 this.partitionHandler = partitionHandler; 1313 } 1314 1315 /** 1316 Enable or disable database partitioning, and set key ranges that will be 1317 used for the partitioning. 1318 <p> 1319 This method may only be called before opening a database. 1320 <p> 1321 @param parts 1322 The number of partitions that will be created. 1323 <p> 1324 @param keys 1325 A MultipleDatabaseEntry that contains the boundary keys for partitioning. 1326 */ setPartitionByRange(int parts, MultipleDataEntry keys)1327 public void setPartitionByRange(int parts, MultipleDataEntry keys) { 1328 this.partitionParts = parts; 1329 this.partitionKeys = keys; 1330 } 1331 1332 /** 1333 Return the function to be called to determine which partition a key resides in. 1334 <p> 1335 This method may be called at any time during the life of the application. 1336 <p> 1337 @return 1338 The function to be called to determine which partition a key resides in. 1339 */ getPartitionHandler()1340 public PartitionHandler getPartitionHandler() { 1341 return partitionHandler; 1342 } 1343 1344 /** 1345 Return the number of partitions the database is configured for. 1346 <p> 1347 This method may be called at any time during the life of the application. 1348 <p> 1349 @return 1350 The number of partitions the database is configured for. 1351 */ getPartitionParts()1352 public int getPartitionParts() { 1353 return partitionParts; 1354 } 1355 1356 /** 1357 Return the array of keys the database is configured to partition with. 1358 <p> 1359 This method may be called at any time during the life of the application. 1360 <p> 1361 @return 1362 The array of keys the database is configured to partition with. 1363 */ getPartitionKeys()1364 public DatabaseEntry getPartitionKeys() { 1365 return partitionKeys; 1366 } 1367 1368 /** 1369 Specify the array of directories the database extents should be created in or 1370 looked for. If the number of directories is less than the number of partitions, 1371 the directories will be used in a round robin fasion. 1372 <p> 1373 This method may only be called before the database is opened. 1374 <p> 1375 @param dirs 1376 The array of directories the database extents should be created in or looked 1377 for. 1378 */ setPartitionDirs(final java.io.File[] dirs)1379 public void setPartitionDirs(final java.io.File[] dirs) { 1380 partitionDirs = dirs; 1381 } 1382 1383 /** 1384 Return the array of directories the database extents should be created in or 1385 looked for. If the number of directories is less than the number of partitions, 1386 the directories will be used in a round robin fasion. 1387 <p> 1388 This method may be called at any time during the life of the application. 1389 <p> 1390 @return 1391 The array of directories the database extents should be created in or looked 1392 for. 1393 */ getPartitionDirs()1394 public java.io.File[] getPartitionDirs() { 1395 return partitionDirs; 1396 } 1397 1398 /** 1399 Set the cache priority for pages referenced by the DB handle. 1400 <p> 1401 The priority of a page biases the replacement algorithm to be more or less 1402 likely to discard a page when space is needed in the buffer pool. The bias 1403 is temporary, and pages will eventually be discarded if they are not 1404 referenced again. The priority setting is only advisory, and does not 1405 guarantee pages will be treated in a specific way. 1406 <p> 1407 @param priority 1408 The desired cache priority. 1409 */ setPriority(final CacheFilePriority priority)1410 public void setPriority(final CacheFilePriority priority) { 1411 this.priority = priority; 1412 } 1413 1414 /** 1415 Return the the cache priority for pages referenced by this handle. 1416 <p> 1417 This method may be called at any time during the life of the application. 1418 <p> 1419 @return 1420 The the cache priority for pages referenced by this handle. 1421 */ getPriority()1422 public CacheFilePriority getPriority() { 1423 return priority; 1424 } 1425 1426 /** 1427 Set the size of the extents used to hold pages in a Queue database, 1428 specified as a number of pages. 1429 <p> 1430 Each extent is created as a separate physical file. If no extent 1431 size is set, the default behavior is to create only a single 1432 underlying database file. 1433 <p> 1434 This method configures a database, not only operations performed using 1435 the specified {@link com.sleepycat.db.Database Database} handle. 1436 <p> 1437 This method may not be called after the database is opened. 1438 If the database already exists when it is opened, 1439 the information specified to this method will be ignored. 1440 <p> 1441 @param queueExtentSize 1442 The number of pages in a Queue database extent. 1443 */ setQueueExtentSize(final int queueExtentSize)1444 public void setQueueExtentSize(final int queueExtentSize) { 1445 this.queueExtentSize = queueExtentSize; 1446 } 1447 1448 /** 1449 Return the size of the extents used to hold pages in a Queue database, 1450 specified as a number of pages. 1451 <p> 1452 This method may be called at any time during the life of the application. 1453 <p> 1454 @return 1455 The size of the extents used to hold pages in a Queue database, 1456 specified as a number of pages. 1457 */ getQueueExtentSize()1458 public int getQueueExtentSize() { 1459 return queueExtentSize; 1460 } 1461 1462 /** 1463 Configure {@link com.sleepycat.db.Database#consume Database.consume} to return key/data pairs in 1464 order, always returning the key/data item from the head of the 1465 queue. 1466 <p> 1467 The default behavior of queue databases is optimized for multiple 1468 readers, and does not guarantee that record will be retrieved in the 1469 order they are added to the queue. Specifically, if a writing 1470 thread adds multiple records to an empty queue, reading threads may 1471 skip some of the initial records when the next call to retrieve a 1472 key/data pair returns. 1473 <p> 1474 This flag configures the {@link com.sleepycat.db.Database#consume Database.consume} method to verify 1475 that the record being returned is in fact the head of the queue. 1476 This will increase contention and reduce concurrency when there are 1477 many reading threads. 1478 <p> 1479 Calling this method only affects the specified {@link com.sleepycat.db.Database Database} handle 1480 (and any other library handles opened within the scope of that handle). 1481 <p> 1482 @param queueInOrder 1483 If true, configure the {@link com.sleepycat.db.Database#consume Database.consume} method to return 1484 key/data pairs in order, always returning the key/data item from the 1485 head of the queue. 1486 A value of false is illegal to this method, that is, once set, the 1487 configuration cannot be cleared. 1488 */ setQueueInOrder(final boolean queueInOrder)1489 public void setQueueInOrder(final boolean queueInOrder) { 1490 this.queueInOrder = queueInOrder; 1491 } 1492 1493 /** 1494 Return true if the {@link com.sleepycat.db.Database#consume Database.consume} method is configured to return 1495 key/data pairs in order, always returning the key/data item from the 1496 head of the queue. 1497 <p> 1498 This method may be called at any time during the life of the application. 1499 <p> 1500 @return 1501 True if the {@link com.sleepycat.db.Database#consume Database.consume} method is configured to return 1502 key/data pairs in order, always returning the key/data item from the 1503 head of the queue. 1504 */ getQueueInOrder()1505 public boolean getQueueInOrder() { 1506 return queueInOrder; 1507 } 1508 1509 /** 1510 Configure the database in read-only mode. 1511 <p> 1512 Any attempt to modify items in the database will fail, regardless 1513 of the actual permissions of any underlying files. 1514 <p> 1515 @param readOnly 1516 If true, configure the database in read-only mode. 1517 */ setReadOnly(final boolean readOnly)1518 public void setReadOnly(final boolean readOnly) { 1519 this.readOnly = readOnly; 1520 } 1521 1522 /** 1523 Return true if the database is configured in read-only mode. 1524 <p> 1525 This method may be called at any time during the life of the application. 1526 <p> 1527 @return 1528 True if the database is configured in read-only mode. 1529 */ getReadOnly()1530 public boolean getReadOnly() { 1531 return readOnly; 1532 } 1533 1534 /** 1535 Configure {@link com.sleepycat.db.Database#append Database.append} to call the function after the 1536 record number has been selected but before the data has been stored 1537 into the database. 1538 <p> 1539 This method configures operations performed using the specified 1540 {@link com.sleepycat.db.Database Database} object, not all operations performed on the underlying 1541 database. 1542 <p> 1543 This method may not be called after the database is opened. 1544 <p> 1545 @param recnoAppender 1546 The function to call after the record number has been selected but 1547 before the data has been stored into the database. 1548 */ setRecordNumberAppender( final RecordNumberAppender recnoAppender)1549 public void setRecordNumberAppender( 1550 final RecordNumberAppender recnoAppender) { 1551 this.recnoAppender = recnoAppender; 1552 } 1553 1554 /** 1555 Return the function to call after the record number has been 1556 selected but before the data has been stored into the database. 1557 <p> 1558 This method may be called at any time during the life of the application. 1559 <p> 1560 @return 1561 The function to call after the record number has been 1562 selected but before the data has been stored into the database. 1563 */ getRecordNumberAppender()1564 public RecordNumberAppender getRecordNumberAppender() { 1565 return recnoAppender; 1566 } 1567 1568 /** 1569 Set the delimiting byte used to mark the end of a record in the backing 1570 source file for the Recno access method. 1571 <p> 1572 This byte is used for variable length records if a backing source 1573 file is specified. If a backing source file is specified and no 1574 delimiting byte was specified, newline characters (that is, ASCII 1575 0x0a) are interpreted as end-of-record markers. 1576 <p> 1577 This method configures a database, not only operations performed using 1578 the specified {@link com.sleepycat.db.Database Database} handle. 1579 <p> 1580 This method may not be called after the database is opened. 1581 If the database already exists when it is opened, 1582 the information specified to this method will be ignored. 1583 <p> 1584 @param recordDelimiter 1585 The delimiting byte used to mark the end of a record in the backing 1586 source file for the Recno access method. 1587 */ setRecordDelimiter(final int recordDelimiter)1588 public void setRecordDelimiter(final int recordDelimiter) { 1589 this.recordDelimiter = recordDelimiter; 1590 } 1591 1592 /** 1593 Return the delimiting byte used to mark the end of a record in the 1594 backing source file for the Recno access method. 1595 <p> 1596 This method may be called at any time during the life of the application. 1597 <p> 1598 @return 1599 The delimiting byte used to mark the end of a record in the 1600 backing source file for the Recno access method. 1601 */ getRecordDelimiter()1602 public int getRecordDelimiter() { 1603 return recordDelimiter; 1604 } 1605 1606 /** 1607 Specify the database record length, in bytes. 1608 <p> 1609 For the Queue access method, specify the record length. For the 1610 Queue access method, the record length must be enough smaller than 1611 the database's page size that at least one record plus the database 1612 page's metadata information can fit on each database page. 1613 <p> 1614 For the Recno access method, specify the records are fixed-length, 1615 not byte-delimited, and the record length. 1616 <p> 1617 Any records added to the database that are less than the specified 1618 length are automatically padded (see 1619 {@link com.sleepycat.db.DatabaseConfig#setRecordPad DatabaseConfig.setRecordPad} for more information). 1620 <p> 1621 Any attempt to insert records into the database that are greater 1622 than the specified length will cause the call to fail. 1623 <p> 1624 This method configures a database, not only operations performed using 1625 the specified {@link com.sleepycat.db.Database Database} handle. 1626 <p> 1627 This method may not be called after the database is opened. 1628 If the database already exists when it is opened, 1629 the information specified to this method will be ignored. 1630 <p> 1631 @param recordLength 1632 The database record length, in bytes. 1633 */ setRecordLength(final int recordLength)1634 public void setRecordLength(final int recordLength) { 1635 this.recordLength = recordLength; 1636 } 1637 1638 /** 1639 Return the database record length, in bytes. 1640 <p> 1641 This method may be called at any time during the life of the application. 1642 <p> 1643 @return 1644 The database record length, in bytes. 1645 */ getRecordLength()1646 public int getRecordLength() { 1647 return recordLength; 1648 } 1649 1650 /** 1651 Configure the Btree to support retrieval by record number. 1652 <p> 1653 Logical record numbers in Btree databases are mutable in the face of 1654 record insertion or deletion. 1655 <p> 1656 Maintaining record counts within a Btree introduces a serious point 1657 of contention, namely the page locations where the record counts are 1658 stored. In addition, the entire database must be locked during both 1659 insertions and deletions, effectively single-threading the database 1660 for those operations. Configuring a Btree for retrieval by record 1661 number can result in serious performance degradation for some 1662 applications and data sets. 1663 <p> 1664 Retrieval by record number may not be configured for a Btree that also 1665 supports duplicate data items. 1666 <p> 1667 Calling this method affects the database, including all threads of 1668 control accessing the database. 1669 <p> 1670 If the database already exists when the database is opened, any database 1671 configuration specified by this method 1672 must be the same as the existing database or an error 1673 will be returned. 1674 <p> 1675 @param btreeRecordNumbers 1676 If true, configure the Btree to support retrieval by record number. 1677 A value of false is illegal to this method, that is, once set, the 1678 configuration cannot be cleared. 1679 */ setBtreeRecordNumbers(final boolean btreeRecordNumbers)1680 public void setBtreeRecordNumbers(final boolean btreeRecordNumbers) { 1681 this.btreeRecordNumbers = btreeRecordNumbers; 1682 } 1683 1684 /** 1685 Return true if the Btree is configured to support retrieval by record number. 1686 <p> 1687 This method may be called at any time during the life of the application. 1688 <p> 1689 @return 1690 True if the Btree is configured to support retrieval by record number. 1691 */ getBtreeRecordNumbers()1692 public boolean getBtreeRecordNumbers() { 1693 return btreeRecordNumbers; 1694 } 1695 1696 /** 1697 Set the padding character for short, fixed-length records for the Queue 1698 and Recno access methods. 1699 <p> 1700 If no pad character is specified, "space" characters (that is, ASCII 1701 0x20) are used for padding. 1702 <p> 1703 This method configures a database, not only operations performed using 1704 the specified {@link com.sleepycat.db.Database Database} handle. 1705 <p> 1706 This method may not be called after the database is opened. 1707 If the database already exists when it is opened, 1708 the information specified to this method will be ignored. 1709 <p> 1710 @param recordPad 1711 The padding character for short, fixed-length records for the Queue 1712 and Recno access methods. 1713 */ setRecordPad(final int recordPad)1714 public void setRecordPad(final int recordPad) { 1715 this.recordPad = recordPad; 1716 } 1717 1718 /** 1719 Return the padding character for short, fixed-length records for the 1720 Queue and Recno access methods. 1721 <p> 1722 This method may be called at any time during the life of the application. 1723 <p> 1724 @return 1725 The padding character for short, fixed-length records for the 1726 Queue and Recno access methods. 1727 */ getRecordPad()1728 public int getRecordPad() { 1729 return recordPad; 1730 } 1731 1732 /** 1733 Set the underlying source file for the Recno access method. 1734 <p> 1735 The purpose of the source file is to provide fast access and 1736 modification to databases that are normally stored as flat text 1737 files. 1738 <p> 1739 The recordSource parameter specifies an underlying flat text 1740 database file that is read to initialize a transient record number 1741 index. In the case of variable length records, the records are 1742 separated, as specified by the 1743 {@link com.sleepycat.db.DatabaseConfig#setRecordDelimiter DatabaseConfig.setRecordDelimiter} method. For example, 1744 standard UNIX byte stream files can be interpreted as a sequence of 1745 variable length records separated by newline characters (that is, ASCII 1746 0x0a). 1747 <p> 1748 In addition, when cached data would normally be written back to the 1749 underlying database file (for example, the {@link com.sleepycat.db.Database#close Database.close} 1750 or {@link com.sleepycat.db.Database#sync Database.sync} methods are called), the in-memory copy 1751 of the database will be written back to the source file. 1752 <p> 1753 By default, the backing source file is read lazily; that is, records 1754 are not read from the file until they are requested by the application. 1755 <b> 1756 If multiple processes (not threads) are accessing a Recno database 1757 concurrently, and are either inserting or deleting records, the backing 1758 source file must be read in its entirety before more than a single 1759 process accesses the database, and only that process should specify 1760 the backing source file as part of opening the database. See the 1761 {@link com.sleepycat.db.DatabaseConfig#setSnapshot DatabaseConfig.setSnapshot} method for more information. 1762 </b> 1763 <p> 1764 <b> 1765 Reading and writing the backing source file cannot be 1766 transaction-protected because it involves filesystem operations that 1767 are not part of the {@link com.sleepycat.db.Database Database} transaction methodology. For 1768 this reason, if a temporary database is used to hold the records, 1769 it is possible to lose the contents of the source file, for example, 1770 if the system crashes at the right instant. If a file is used to 1771 hold the database, normal database recovery on that file can be used 1772 to prevent information loss, although it is still possible that the 1773 contents of the source file will be lost if the system crashes. 1774 </b> 1775 <p> 1776 The source file must already exist (but may be zero-length) when 1777 the database is opened. 1778 <p> 1779 It is not an error to specify a read-only source file when creating 1780 a database, nor is it an error to modify the resulting database. 1781 However, any attempt to write the changes to the backing source file 1782 using either the {@link com.sleepycat.db.Database#sync Database.sync} or {@link com.sleepycat.db.Database#close Database.close} 1783 methods will fail, of course. Specify the noSync argument to the 1784 {@link com.sleepycat.db.Database#close Database.close} method to stop it from attempting to write 1785 the changes to the backing file; instead, they will be silently 1786 discarded. 1787 <p> 1788 For all of the previous reasons, the source file is generally used 1789 to specify databases that are read-only for Berkeley DB 1790 applications; and that are either generated on the fly by software 1791 tools or modified using a different mechanism -- for example, a text 1792 editor. 1793 <p> 1794 This method configures operations performed using the specified 1795 {@link com.sleepycat.db.Database Database} object, not all operations performed on the underlying 1796 database. 1797 <p> 1798 This method may not be called after the database is opened. 1799 If the database already exists when it is opened, 1800 the information specified to this method must be the same as that 1801 historically used to create the database or corruption can occur. 1802 <p> 1803 @param recordSource 1804 The name of an underlying flat text database file that is read to 1805 initialize a transient record number index. In the case of variable 1806 length records, the records are separated, as specified by the 1807 {@link com.sleepycat.db.DatabaseConfig#setRecordDelimiter DatabaseConfig.setRecordDelimiter} method. For example, 1808 standard UNIX byte stream files can be interpreted as a sequence of 1809 variable length records separated by newline characters (that is, ASCII 1810 0x0a). 1811 */ setRecordSource(final java.io.File recordSource)1812 public void setRecordSource(final java.io.File recordSource) { 1813 this.recordSource = recordSource; 1814 } 1815 1816 /** 1817 Return the name of an underlying flat text database file that is 1818 read to initialize a transient record number index. 1819 <p> 1820 This method may be called at any time during the life of the application. 1821 <p> 1822 @return 1823 The name of an underlying flat text database file that is 1824 read to initialize a transient record number index. 1825 */ getRecordSource()1826 public java.io.File getRecordSource() { 1827 return recordSource; 1828 } 1829 1830 /** 1831 Configure the logical record numbers to be mutable, and change as 1832 records are added to and deleted from the database. 1833 <p> 1834 For example, the deletion of record number 4 causes records numbered 1835 5 and greater to be renumbered downward by one. If a cursor was 1836 positioned to record number 4 before the deletion, it will refer to 1837 the new record number 4, if any such record exists, after the 1838 deletion. If a cursor was positioned after record number 4 before 1839 the deletion, it will be shifted downward one logical record, 1840 continuing to refer to the same record as it did before. 1841 <p> 1842 Creating new records will cause the creation of multiple records if 1843 the record number is more than one greater than the largest record 1844 currently in the database. For example, creating record 28, when 1845 record 25 was previously the last record in the database, will 1846 create records 26 and 27 as well as 28. Attempts to retrieve 1847 records that were created in this manner will result in an error 1848 return of {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY}. 1849 <p> 1850 If a created record is not at the end of the database, all records 1851 following the new record will be automatically renumbered upward by one. 1852 For example, the creation of a new record numbered 8 causes records 1853 numbered 8 and greater to be renumbered upward by one. If a cursor was 1854 positioned to record number 8 or greater before the insertion, it will 1855 be shifted upward one logical record, continuing to refer to the same 1856 record as it did before. 1857 <p> 1858 For these reasons, concurrent access to a Recno database configured 1859 with mutable record numbers may be largely meaningless, although it 1860 is supported. 1861 <p> 1862 Calling this method affects the database, including all threads of 1863 control accessing the database. 1864 <p> 1865 If the database already exists when the database is opened, any database 1866 configuration specified by this method 1867 must be the same as the existing database or an error 1868 will be returned. 1869 <p> 1870 @param renumbering 1871 If true, configure the logical record numbers to be mutable, and 1872 change as records are added to and deleted from the database. 1873 A value of false is illegal to this method, that is, once set, the 1874 configuration cannot be cleared. 1875 */ setRenumbering(final boolean renumbering)1876 public void setRenumbering(final boolean renumbering) { 1877 this.renumbering = renumbering; 1878 } 1879 1880 /** 1881 Return true if the logical record numbers are mutable, and change as 1882 records are added to and deleted from the database. 1883 <p> 1884 This method may be called at any time during the life of the application. 1885 <p> 1886 @return 1887 True if the logical record numbers are mutable, and change as 1888 records are added to and deleted from the database. 1889 */ getRenumbering()1890 public boolean getRenumbering() { 1891 return renumbering; 1892 } 1893 1894 /** 1895 Configure the Btree to not do reverse splits. 1896 <p> 1897 As pages are emptied in a database, the Btree implementation 1898 attempts to coalesce empty pages into higher-level pages in order 1899 to keep the database as small as possible and minimize search time. 1900 This can hurt performance in applications with cyclical data 1901 demands; that is, applications where the database grows and shrinks 1902 repeatedly. For example, because Berkeley DB does page-level locking, 1903 the maximum level of concurrency in a database of two pages is far 1904 smaller than that in a database of 100 pages, so a database that has 1905 shrunk to a minimal size can cause severe deadlocking when a new 1906 cycle of data insertion begins. 1907 <p> 1908 Calling this method only affects the specified {@link com.sleepycat.db.Database Database} handle 1909 (and any other library handles opened within the scope of that handle). 1910 <p> 1911 @param reverseSplitOff 1912 If true, configure the Btree to not do reverse splits. 1913 A value of false is illegal to this method, that is, once set, the 1914 configuration cannot be cleared. 1915 */ setReverseSplitOff(final boolean reverseSplitOff)1916 public void setReverseSplitOff(final boolean reverseSplitOff) { 1917 this.reverseSplitOff = reverseSplitOff; 1918 } 1919 1920 /** 1921 Return true if the Btree has been configured to not do reverse splits. 1922 <p> 1923 This method may be called at any time during the life of the application. 1924 <p> 1925 @return 1926 True if the Btree has been configured to not do reverse splits. 1927 */ getReverseSplitOff()1928 public boolean getReverseSplitOff() { 1929 return reverseSplitOff; 1930 } 1931 1932 /** 1933 Configure the database to support sorted, duplicate data items. 1934 <p> 1935 Insertion when the key of the key/data pair being inserted already 1936 exists in the database will be successful. The ordering of 1937 duplicates in the database is determined by the duplicate comparison 1938 function. 1939 <p> 1940 If the application does not specify a duplicate data item comparison 1941 function, a default lexical comparison will be used. 1942 <p> 1943 If a primary database is to be associated with one or more secondary 1944 databases, it may not be configured for duplicates. 1945 <p> 1946 A Btree that supports duplicate data items cannot also be configured 1947 for retrieval by record number. 1948 <p> 1949 Calling this method affects the database, including all threads of 1950 control accessing the database. 1951 <p> 1952 If the database already exists when the database is opened, any database 1953 configuration specified by this method 1954 must be the same as the existing database or an error 1955 will be returned. 1956 <p> 1957 @param sortedDuplicates 1958 If true, configure the database to support duplicate data items. 1959 A value of false is illegal to this method, that is, once set, the 1960 configuration cannot be cleared. 1961 */ setSortedDuplicates(final boolean sortedDuplicates)1962 public void setSortedDuplicates(final boolean sortedDuplicates) { 1963 this.sortedDuplicates = sortedDuplicates; 1964 } 1965 1966 /** 1967 Return true if the database is configured to support sorted duplicate data 1968 items. 1969 <p> 1970 This method may be called at any time during the life of the application. 1971 <p> 1972 @return 1973 True if the database is configured to support sorted duplicate data 1974 items. 1975 */ getSortedDuplicates()1976 public boolean getSortedDuplicates() { 1977 return sortedDuplicates; 1978 } 1979 1980 /** 1981 Configure the database to support unsorted duplicate data items. 1982 <p> 1983 Insertion when the key of the key/data pair being inserted already 1984 exists in the database will be successful. The ordering of 1985 duplicates in the database is determined by the order of insertion, 1986 unless the ordering is otherwise specified by use of a database 1987 cursor operation. 1988 <p> 1989 If a primary database is to be associated with one or more secondary 1990 databases, it may not be configured for duplicates. 1991 <p> 1992 Sorted duplicates are preferred to unsorted duplicates for 1993 performance reasons. Unsorted duplicates should only be used by 1994 applications wanting to order duplicate data items manually. 1995 <p> 1996 Calling this method affects the database, including all threads of 1997 control accessing the database. 1998 <p> 1999 If the database already exists when the database is opened, any database 2000 configuration specified by this method 2001 must be the same as the existing database or an error 2002 will be returned. 2003 <p> 2004 @param unsortedDuplicates 2005 If true, configure the database to support unsorted duplicate data items. 2006 A value of false is illegal to this method, that is, once set, the 2007 configuration cannot be cleared. 2008 */ setUnsortedDuplicates(final boolean unsortedDuplicates)2009 public void setUnsortedDuplicates(final boolean unsortedDuplicates) { 2010 this.unsortedDuplicates = unsortedDuplicates; 2011 } 2012 2013 /** 2014 Return true if the database is configured to support duplicate data items. 2015 <p> 2016 This method may be called at any time during the life of the application. 2017 <p> 2018 @return 2019 True if the database is configured to support duplicate data items. 2020 */ getUnsortedDuplicates()2021 public boolean getUnsortedDuplicates() { 2022 return unsortedDuplicates; 2023 } 2024 2025 /** 2026 Specify that any specified backing source file be read in its entirety 2027 when the database is opened. 2028 <p> 2029 If this flag is not specified, the backing source file may be read 2030 lazily. 2031 <p> 2032 Calling this method only affects the specified {@link com.sleepycat.db.Database Database} handle 2033 (and any other library handles opened within the scope of that handle). 2034 <p> 2035 @param snapshot 2036 If true, any specified backing source file will be read in its entirety 2037 when the database is opened. 2038 A value of false is illegal to this method, that is, once set, the 2039 configuration cannot be cleared. 2040 */ setSnapshot(final boolean snapshot)2041 public void setSnapshot(final boolean snapshot) { 2042 this.snapshot = snapshot; 2043 } 2044 2045 /** 2046 Return true if the any specified backing source file will be read in its 2047 entirety when the database is opened. 2048 <p> 2049 This method may be called at any time during the life of the application. 2050 <p> 2051 @return 2052 True if the any specified backing source file will be read in its 2053 entirety when the database is opened. 2054 */ getSnapshot()2055 public boolean getSnapshot() { 2056 return snapshot; 2057 } 2058 2059 /** 2060 Return true if the database open is enclosed within a transaction. 2061 <p> 2062 This method may be called at any time during the life of the application. 2063 <p> 2064 @return 2065 True if the database open is enclosed within a transaction. 2066 */ getTransactional()2067 public boolean getTransactional() { 2068 return transactional; 2069 } 2070 2071 /** 2072 Enclose the database open within a transaction. 2073 <p> 2074 If the call succeeds, the open operation will be recoverable. If 2075 the call fails, no database will have been created. 2076 <p> 2077 All future operations on this database, which are not explicitly 2078 enclosed in a transaction by the application, will be enclosed in 2079 in a transaction within the library. 2080 <p> 2081 @param transactional 2082 If true, enclose the database open within a transaction. 2083 */ setTransactional(final boolean transactional)2084 public void setTransactional(final boolean transactional) { 2085 this.transactional = transactional; 2086 } 2087 2088 /** 2089 Configure the database environment to not write log records for this 2090 database. 2091 <p> 2092 This means that updates of this database exhibit the ACI (atomicity, 2093 consistency, and isolation) properties, but not D (durability); that 2094 is, database integrity will be maintained, but if the application 2095 or system fails, integrity will not persist. The database file must 2096 be verified and/or restored from backup after a failure. In order 2097 to ensure integrity after application shut down, the database 2098 must be flushed to disk before the database handles are closed, 2099 or all 2100 database changes must be flushed from the database environment cache 2101 using {@link com.sleepycat.db.Environment#checkpoint Environment.checkpoint}. 2102 <p> 2103 All database handles for a single physical file must call this method, 2104 including database handles for different databases in a physical file. 2105 <p> 2106 Calling this method only affects the specified {@link com.sleepycat.db.Database Database} handle 2107 (and any other library handles opened within the scope of that handle). 2108 <p> 2109 @param transactionNotDurable 2110 If true, configure the database environment to not write log records 2111 for this database. 2112 A value of false is illegal to this method, that is, once set, the 2113 configuration cannot be cleared. 2114 */ setTransactionNotDurable(final boolean transactionNotDurable)2115 public void setTransactionNotDurable(final boolean transactionNotDurable) { 2116 this.transactionNotDurable = transactionNotDurable; 2117 } 2118 2119 /** 2120 Return true if the database environment is configured to not write log 2121 records for this database. 2122 <p> 2123 This method may be called at any time during the life of the application. 2124 <p> 2125 @return 2126 True if the database environment is configured to not write log 2127 records for this database. 2128 */ getTransactionNotDurable()2129 public boolean getTransactionNotDurable() { 2130 return transactionNotDurable; 2131 } 2132 2133 /** 2134 Configure the database to be physically truncated by truncating the 2135 underlying file, discarding all previous databases it might have 2136 held. 2137 <p> 2138 Underlying filesystem primitives are used to implement this 2139 configuration. For this reason, it is applicable only to a physical 2140 file and cannot be used to discard databases within a file. 2141 <p> 2142 This configuration option cannot be lock or transaction-protected, and 2143 it is an error to specify it in a locking or transaction-protected 2144 database environment. 2145 <p> 2146 @param truncate 2147 If true, configure the database to be physically truncated by truncating 2148 the underlying file, discarding all previous databases it might have 2149 held. 2150 */ setTruncate(final boolean truncate)2151 public void setTruncate(final boolean truncate) { 2152 this.truncate = truncate; 2153 } 2154 2155 /** 2156 Return true if the database has been configured to be physically truncated 2157 by truncating the underlying file, discarding all previous databases 2158 it might have held. 2159 <p> 2160 This method may be called at any time during the life of the application. 2161 <p> 2162 @return 2163 True if the database has been configured to be physically truncated 2164 by truncating the underlying file, discarding all previous databases 2165 it might have held. 2166 */ getTruncate()2167 public boolean getTruncate() { 2168 return truncate; 2169 } 2170 2171 /** 2172 Configure the type of the database. 2173 <p> 2174 If they type is DB_UNKNOWN, the database must already exist. 2175 <p> 2176 @param type 2177 The type of the database. 2178 */ setType(final DatabaseType type)2179 public void setType(final DatabaseType type) { 2180 this.type = type; 2181 } 2182 2183 /** 2184 Return the type of the database. 2185 <p> 2186 This method may be used to determine the type of the database after 2187 opening it. 2188 <p> 2189 This method may not be called before the 2190 database has been opened. 2191 <p> 2192 @return 2193 The type of the database. 2194 */ getType()2195 public DatabaseType getType() { 2196 return type; 2197 } 2198 2199 /* package */ createDatabase(final DbEnv dbenv)2200 Db createDatabase(final DbEnv dbenv) 2201 throws DatabaseException { 2202 2203 return new Db(dbenv, 0); 2204 } 2205 2206 /* package */ openDatabase(final DbEnv dbenv, final DbTxn txn, final String fileName, final String databaseName)2207 Db openDatabase(final DbEnv dbenv, 2208 final DbTxn txn, 2209 final String fileName, 2210 final String databaseName) 2211 throws DatabaseException, java.io.FileNotFoundException { 2212 2213 final Db db = createDatabase(dbenv); 2214 // The DB_THREAD flag is inherited from the environment 2215 // (defaulting to ON if no environment handle is supplied). 2216 boolean threaded = (dbenv == null || 2217 (dbenv.get_open_flags() & DbConstants.DB_THREAD) != 0); 2218 2219 int openFlags = 0; 2220 openFlags |= allowCreate ? DbConstants.DB_CREATE : 0; 2221 openFlags |= readUncommitted ? DbConstants.DB_READ_UNCOMMITTED : 0; 2222 openFlags |= exclusiveCreate ? DbConstants.DB_EXCL : 0; 2223 openFlags |= multiversion ? DbConstants.DB_MULTIVERSION : 0; 2224 openFlags |= noMMap ? DbConstants.DB_NOMMAP : 0; 2225 openFlags |= readOnly ? DbConstants.DB_RDONLY : 0; 2226 openFlags |= threaded ? DbConstants.DB_THREAD : 0; 2227 openFlags |= truncate ? DbConstants.DB_TRUNCATE : 0; 2228 2229 if (transactional && txn == null) 2230 openFlags |= DbConstants.DB_AUTO_COMMIT; 2231 2232 boolean succeeded = false; 2233 try { 2234 configureDatabase(db, DEFAULT); 2235 db.open(txn, fileName, databaseName, type.getId(), openFlags, mode); 2236 succeeded = true; 2237 return db; 2238 } finally { 2239 if (!succeeded) 2240 try { 2241 db.close(0); 2242 } catch (Throwable t) { 2243 // Ignore it -- an exception is already in flight. 2244 } 2245 } 2246 } 2247 2248 /* package */ configureDatabase(final Db db, final DatabaseConfig oldConfig)2249 void configureDatabase(final Db db, final DatabaseConfig oldConfig) 2250 throws DatabaseException { 2251 2252 int dbFlags = 0; 2253 dbFlags |= checksum ? DbConstants.DB_CHKSUM : 0; 2254 dbFlags |= btreeRecordNumbers ? DbConstants.DB_RECNUM : 0; 2255 dbFlags |= queueInOrder ? DbConstants.DB_INORDER : 0; 2256 dbFlags |= renumbering ? DbConstants.DB_RENUMBER : 0; 2257 dbFlags |= reverseSplitOff ? DbConstants.DB_REVSPLITOFF : 0; 2258 dbFlags |= sortedDuplicates ? DbConstants.DB_DUPSORT : 0; 2259 dbFlags |= snapshot ? DbConstants.DB_SNAPSHOT : 0; 2260 dbFlags |= unsortedDuplicates ? DbConstants.DB_DUP : 0; 2261 dbFlags |= transactionNotDurable ? DbConstants.DB_TXN_NOT_DURABLE : 0; 2262 if (!db.getPrivateDbEnv()) 2263 dbFlags |= (password != null) ? DbConstants.DB_ENCRYPT : 0; 2264 2265 if (dbFlags != 0) 2266 db.set_flags(dbFlags); 2267 2268 if (btMinKey != oldConfig.btMinKey) 2269 db.set_bt_minkey(btMinKey); 2270 if (byteOrder != oldConfig.byteOrder) 2271 db.set_lorder(byteOrder); 2272 if ((cacheSize != oldConfig.cacheSize || 2273 cacheCount != oldConfig.cacheCount) && db.getPrivateDbEnv()) 2274 db.set_cachesize(cacheSize, cacheCount); 2275 if (createDir != oldConfig.createDir && createDir != null && 2276 !createDir.equals(oldConfig.createDir)) 2277 db.set_create_dir(createDir.toString()); 2278 if (errorStream != oldConfig.errorStream) 2279 db.set_error_stream(errorStream); 2280 if (errorPrefix != oldConfig.errorPrefix) 2281 db.set_errpfx(errorPrefix); 2282 if (hashFillFactor != oldConfig.hashFillFactor) 2283 db.set_h_ffactor(hashFillFactor); 2284 if (hashNumElements != oldConfig.hashNumElements) 2285 db.set_h_nelem(hashNumElements); 2286 if (heapSize != oldConfig.heapSize) 2287 db.set_heapsize(heapSize); 2288 if (heapRegionSize != oldConfig.heapRegionSize) 2289 db.set_heap_regionsize(heapRegionSize); 2290 if (messageStream != oldConfig.messageStream) 2291 db.set_message_stream(messageStream); 2292 if (pageSize != oldConfig.pageSize) 2293 db.set_pagesize(pageSize); 2294 2295 if (partitionDirs != null && 2296 partitionDirs != oldConfig.partitionDirs) { 2297 String[] partitionDirArray = new String[partitionDirs.length]; 2298 for (int i = 0; i < partitionDirArray.length; i++) 2299 partitionDirArray[i] = partitionDirs[i].toString(); 2300 db.set_partition_dirs(partitionDirArray); 2301 } 2302 if (password != oldConfig.password && db.getPrivateDbEnv()) 2303 db.set_encrypt(password, DbConstants.DB_ENCRYPT_AES); 2304 if (priority != oldConfig.priority) 2305 db.set_priority(priority.getFlag()); 2306 if (queueExtentSize != oldConfig.queueExtentSize) 2307 db.set_q_extentsize(queueExtentSize); 2308 if (recordDelimiter != oldConfig.recordDelimiter) 2309 db.set_re_delim(recordDelimiter); 2310 if (recordLength != oldConfig.recordLength) 2311 db.set_re_len(recordLength); 2312 if (recordPad != oldConfig.recordPad) 2313 db.set_re_pad(recordPad); 2314 if (recordSource != oldConfig.recordSource) 2315 db.set_re_source( 2316 (recordSource == null) ? null : recordSource.toString()); 2317 if (noWaitDbExclusiveLock != null && 2318 oldConfig.noWaitDbExclusiveLock != noWaitDbExclusiveLock) 2319 db.set_lk_exclusive(noWaitDbExclusiveLock ? 1 : 0); 2320 2321 if (btreeComparator != oldConfig.btreeComparator) 2322 db.set_bt_compare(btreeComparator); 2323 if (btreeCompressor != oldConfig.btreeCompressor) 2324 db.set_bt_compress(btreeCompressor, btreeCompressor); 2325 if (btreePrefixCalculator != oldConfig.btreePrefixCalculator) 2326 db.set_bt_prefix(btreePrefixCalculator); 2327 if (duplicateComparator != oldConfig.duplicateComparator) 2328 db.set_dup_compare(duplicateComparator); 2329 if (feedbackHandler != oldConfig.feedbackHandler) 2330 db.set_feedback(feedbackHandler); 2331 if (errorHandler != oldConfig.errorHandler) 2332 db.set_errcall(errorHandler); 2333 if (hashComparator != oldConfig.hashComparator) 2334 db.set_h_compare(hashComparator); 2335 if (hasher != oldConfig.hasher) 2336 db.set_h_hash(hasher); 2337 if (messageHandler != oldConfig.messageHandler) 2338 db.set_msgcall(messageHandler); 2339 if (partitionHandler != oldConfig.partitionHandler || 2340 partitionKeys != oldConfig.partitionKeys || 2341 partitionParts != oldConfig.partitionParts) 2342 db.set_partition(partitionParts, partitionKeys, partitionHandler); 2343 if (recnoAppender != oldConfig.recnoAppender) 2344 db.set_append_recno(recnoAppender); 2345 if (panicHandler != oldConfig.panicHandler) 2346 db.set_paniccall(panicHandler); 2347 } 2348 2349 /* package */ DatabaseConfig(final Db db)2350 DatabaseConfig(final Db db) 2351 throws DatabaseException { 2352 2353 type = DatabaseType.fromInt(db.get_type()); 2354 2355 final int openFlags = db.get_open_flags(); 2356 allowCreate = (openFlags & DbConstants.DB_CREATE) != 0; 2357 readUncommitted = (openFlags & DbConstants.DB_READ_UNCOMMITTED) != 0; 2358 exclusiveCreate = (openFlags & DbConstants.DB_EXCL) != 0; 2359 multiversion = (openFlags & DbConstants.DB_MULTIVERSION) != 0; 2360 noMMap = (openFlags & DbConstants.DB_NOMMAP) != 0; 2361 readOnly = (openFlags & DbConstants.DB_RDONLY) != 0; 2362 truncate = (openFlags & DbConstants.DB_TRUNCATE) != 0; 2363 2364 final int dbFlags = db.get_flags(); 2365 checksum = (dbFlags & DbConstants.DB_CHKSUM) != 0; 2366 btreeRecordNumbers = (dbFlags & DbConstants.DB_RECNUM) != 0; 2367 queueInOrder = (dbFlags & DbConstants.DB_INORDER) != 0; 2368 renumbering = (dbFlags & DbConstants.DB_RENUMBER) != 0; 2369 reverseSplitOff = (dbFlags & DbConstants.DB_REVSPLITOFF) != 0; 2370 sortedDuplicates = (dbFlags & DbConstants.DB_DUPSORT) != 0; 2371 snapshot = (dbFlags & DbConstants.DB_SNAPSHOT) != 0; 2372 unsortedDuplicates = !sortedDuplicates && ((dbFlags & DbConstants.DB_DUP) != 0); 2373 transactionNotDurable = (dbFlags & DbConstants.DB_TXN_NOT_DURABLE) != 0; 2374 2375 if (type == DatabaseType.BTREE) { 2376 btMinKey = db.get_bt_minkey(); 2377 } 2378 byteOrder = db.get_lorder(); 2379 // Call get_cachesize* on the DbEnv to avoid this error: 2380 // DB->get_cachesize: method not permitted in shared environment 2381 cacheSize = db.get_env().get_cachesize(); 2382 cacheCount = db.get_env().get_cachesize_ncache(); 2383 errorStream = db.get_error_stream(); 2384 errorPrefix = db.get_errpfx(); 2385 if (type == DatabaseType.HASH) { 2386 hashFillFactor = db.get_h_ffactor(); 2387 hashNumElements = db.get_h_nelem(); 2388 } 2389 if (type == DatabaseType.HEAP) { 2390 heapSize = db.get_heapsize(); 2391 heapRegionSize = db.get_heap_regionsize(); 2392 } 2393 messageStream = db.get_message_stream(); 2394 pageSize = db.get_pagesize(); 2395 // Not available by design 2396 password = ((dbFlags & DbConstants.DB_ENCRYPT) != 0) ? "" : null; 2397 priority = CacheFilePriority.fromFlag(db.get_priority()); 2398 if (type == DatabaseType.QUEUE) { 2399 queueExtentSize = db.get_q_extentsize(); 2400 } 2401 if (type == DatabaseType.QUEUE || type == DatabaseType.RECNO) { 2402 recordLength = db.get_re_len(); 2403 recordPad = db.get_re_pad(); 2404 } 2405 if (type == DatabaseType.RECNO) { 2406 recordDelimiter = db.get_re_delim(); 2407 recordSource = (db.get_re_source() == null) ? null : 2408 new java.io.File(db.get_re_source()); 2409 } 2410 transactional = db.get_transactional(); 2411 createDir = (db.get_create_dir() == null) ? null: 2412 new java.io.File(db.get_create_dir()); 2413 2414 String[] partitionDirArray = db.get_partition_dirs(); 2415 if (partitionDirArray == null) 2416 partitionDirs = null; 2417 else { 2418 partitionDirs = new java.io.File[partitionDirArray.length]; 2419 for (int i = 0; i < partitionDirArray.length; i++) 2420 partitionDirs[i] = new java.io.File(partitionDirArray[i]); 2421 } 2422 2423 int noWaitDbExclLock = db.get_lk_exclusive(); 2424 if (noWaitDbExclLock == 2) 2425 noWaitDbExclusiveLock = Boolean.TRUE; 2426 else if (noWaitDbExclLock == 1) 2427 noWaitDbExclusiveLock = Boolean.FALSE; 2428 else noWaitDbExclusiveLock = null; 2429 2430 btreeComparator = db.get_bt_compare(); 2431 btreeCompressor = db.get_bt_compress(); 2432 btreePrefixCalculator = db.get_bt_prefix(); 2433 duplicateComparator = db.get_dup_compare(); 2434 feedbackHandler = db.get_feedback(); 2435 errorHandler = db.get_errcall(); 2436 hashComparator = db.get_h_compare(); 2437 hasher = db.get_h_hash(); 2438 messageHandler = db.get_msgcall(); 2439 partitionParts = db.get_partition_parts(); 2440 partitionKeys = db.get_partition_keys(); 2441 partitionHandler = db.get_partition_callback(); 2442 recnoAppender = db.get_append_recno(); 2443 panicHandler = db.get_paniccall(); 2444 } 2445 } 2446