1/*- 2 * See the file LICENSE for redistribution information. 3 * 4 * Copyright (c) 2002-2009 Oracle. All rights reserved. 5 * 6 * $Id$ 7 */ 8 9package com.sleepycat.db; 10 11import com.sleepycat.db.internal.Db; 12import com.sleepycat.db.internal.DbConstants; 13import com.sleepycat.db.internal.DbSequence; 14import com.sleepycat.db.internal.Dbc; 15 16/** 17A database handle. 18<p> 19Database attributes are specified in the {@link com.sleepycat.db.DatabaseConfig DatabaseConfig} class. 20<p> 21Database handles are free-threaded unless opened in an environment 22that is not free-threaded. 23<p> 24To open an existing database with default attributes: 25<blockquote><pre> 26 Environment env = new Environment(home, null); 27 Database myDatabase = env.openDatabase(null, "mydatabase", null); 28</pre></blockquote> 29To create a transactional database that supports duplicates: 30<blockquote><pre> 31 DatabaseConfig dbConfig = new DatabaseConfig(); 32 dbConfig.setTransactional(true); 33 dbConfig.setAllowCreate(true); 34 dbConfig.setSortedDuplicates(true); 35 Database newlyCreateDb = env.openDatabase(txn, "mydatabase", dbConfig); 36</pre></blockquote> 37*/ 38public class Database { 39 Db db; 40 private int autoCommitFlag; 41 int rmwFlag; 42 43 /* package */ 44 Database(final Db db) 45 throws DatabaseException { 46 47 this.db = db; 48 db.wrapper = this; 49 this.autoCommitFlag = 50 db.get_transactional() ? DbConstants.DB_AUTO_COMMIT : 0; 51 rmwFlag = ((db.get_env().get_open_flags() & 52 DbConstants.DB_INIT_LOCK) != 0) ? DbConstants.DB_RMW : 0; 53 } 54 55 /** 56 Open a database. 57<p> 58The database is represented by the file and database parameters. 59<p> 60The currently supported database file formats (or <em>access 61methods</em>) are Btree, Hash, Queue, and Recno. The Btree format is a 62representation of a sorted, balanced tree structure. The Hash format 63is an extensible, dynamic hashing scheme. The Queue format supports 64fast access to fixed-length records accessed sequentially or by logical 65record number. The Recno format supports fixed- or variable-length 66records, accessed sequentially or by logical record number, and 67optionally backed by a flat text file. 68<p> 69Storage and retrieval are based on key/data pairs; see {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} 70for more information. 71<p> 72Opening a database is a relatively expensive operation, and maintaining 73a set of open databases will normally be preferable to repeatedly 74opening and closing the database for each new query. 75<p> 76In-memory databases never intended to be preserved on disk may be 77created by setting both the fileName and databaseName parameters to 78null. Note that in-memory databases can only ever be shared by sharing 79the single database handle that created them, in circumstances where 80doing so is safe. The environment variable <code>TMPDIR</code> may 81be used as a directory in which to create temporary backing files. 82<p> 83@param filename 84The name of an underlying file that will be used to back the database. 85On Windows platforms, this argument will be interpreted as a UTF-8 86string, which is equivalent to ASCII for Latin characters. 87<p> 88@param databaseName 89An optional parameter that allows applications to have multiple 90databases in a single file. Although no databaseName parameter needs 91to be specified, it is an error to attempt to open a second database in 92a physical file that was not initially created using a databaseName 93parameter. Further, the databaseName parameter is not supported by the 94Queue format. 95<p> 96@param config The database open attributes. If null, default attributes are used. 97 */ 98 public Database(final String filename, 99 final String databaseName, 100 final DatabaseConfig config) 101 throws DatabaseException, java.io.FileNotFoundException { 102 103 this(DatabaseConfig.checkNull(config).openDatabase(null, null, 104 filename, databaseName)); 105 // Set up dbenv.wrapper 106 new Environment(db.get_env()); 107 } 108 109 /** 110 Flush any cached database information to disk and discard the database 111handle. 112<p> 113The database handle should not be closed while any other handle that 114refers to it is not yet closed; for example, database handles should not 115be closed while cursor handles into the database remain open, or 116transactions that include operations on the database have not yet been 117committed or aborted. Specifically, this includes {@link com.sleepycat.db.Cursor Cursor} and 118{@link com.sleepycat.db.Transaction Transaction} handles. 119<p> 120Because key/data pairs are cached in memory, failing to sync the file 121with the {@link com.sleepycat.db.Database#close Database.close} or {@link com.sleepycat.db.Database#sync Database.sync} methods 122may result in inconsistent or lost information. 123<p> 124When multiple threads are using the {@link com.sleepycat.db.Database Database} handle 125concurrently, only a single thread may call this method. 126<p> 127The database handle may not be accessed again after this method is 128called, regardless of the method's success or failure. 129<p> 130When called on a database that is the primary database for a secondary 131index, the primary database should be closed only after all secondary 132indices which reference it have been closed. 133@param noSync 134Do not flush cached information to disk. The noSync parameter is a 135dangerous option. It should be set only if the application is doing 136logging (with transactions) so that the database is recoverable after a 137system or application crash, or if the database is always generated from 138scratch after any system or application crash. 139<b> 140It is important to understand that flushing cached information to disk 141only minimizes the window of opportunity for corrupted data. 142<p> 143</b> 144Although unlikely, it is possible for database corruption to happen if 145a system or application crash occurs while writing data to the database. 146To ensure that database corruption never occurs, applications must 147either: use transactions and logging with automatic recovery; use 148logging and application-specific recovery; or edit a copy of the 149database, and once all applications using the database have successfully 150called this method, atomically replace the original database with the 151updated copy. 152<p> 153<p> 154@throws DatabaseException if a failure occurs. 155 */ 156 public void close(final boolean noSync) 157 throws DatabaseException { 158 159 db.close(noSync ? DbConstants.DB_NOSYNC : 0); 160 } 161 162 /** 163 Flush any cached database information to disk and discard the database 164handle. 165<p> 166The database handle should not be closed while any other handle that 167refers to it is not yet closed; for example, database handles should not 168be closed while cursor handles into the database remain open, or 169transactions that include operations on the database have not yet been 170committed or aborted. Specifically, this includes {@link com.sleepycat.db.Cursor Cursor} and 171{@link com.sleepycat.db.Transaction Transaction} handles. 172<p> 173Because key/data pairs are cached in memory, failing to sync the file 174with the {@link com.sleepycat.db.Database#close Database.close} or {@link com.sleepycat.db.Database#sync Database.sync} methods 175may result in inconsistent or lost information. 176<p> 177When multiple threads are using the {@link com.sleepycat.db.Database Database} handle 178concurrently, only a single thread may call this method. 179<p> 180The database handle may not be accessed again after this method is 181called, regardless of the method's success or failure. 182<p> 183When called on a database that is the primary database for a secondary 184index, the primary database should be closed only after all secondary 185indices which reference it have been closed. 186<p> 187<p> 188@throws DatabaseException if a failure occurs. 189 */ 190 public void close() 191 throws DatabaseException { 192 193 close(false); 194 } 195 196 /** 197 Compact a Btree or Recno database or returns unused Btree, 198 Hash or Recno database pages to the underlying filesystem. 199 @param txn 200 If the operation is part of an application-specified transaction, the txnid 201 parameter is a transaction handle returned from {@link 202 Environment#beginTransaction}, otherwise <code>null</code>. 203 If no transaction handle is specified, but the operation occurs in a 204 transactional database, the operation will be implicitly transaction 205 protected using multiple transactions. Transactions will be comitted at 206 points to avoid holding much of the tree locked. 207 Any deadlocks encountered will be cause the operation to retried from 208 the point of the last commit. 209 @param start 210 If not <code>null</code>, the <code>start</code> parameter is the starting 211 point for compaction in a Btree or Recno database. Compaction will start 212 at the smallest key greater than or equal to the specified key. If 213 <code>null</code>, compaction will start at the beginning of the database. 214 @param stop 215 If not <code>null</code>, the <code>stop</code> parameter is the stopping 216 point for compaction in a Btree or Recno database. Compaction will stop at 217 the page with the smallest key greater than the specified key. If 218 <code>null</code>, compaction will stop at the end of the database. 219 @param end 220 If not <code>null</code>, the <code>end</code> parameter will be filled in 221 with the key marking the end of the compaction operation in a Btree or 222 Recno database. It is generally the first key of the page where processing 223 stopped. 224 @param config The compaction operation attributes. If null, default attributes are used. 225 **/ 226 public CompactStats compact(final Transaction txn, 227 final DatabaseEntry start, 228 final DatabaseEntry stop, 229 final DatabaseEntry end, 230 CompactConfig config) 231 throws DatabaseException { 232 233 config = CompactConfig.checkNull(config); 234 CompactStats compact = new CompactStats(config.getFillPercent(), 235 config.getTimeout(), config.getMaxPages()); 236 db.compact((txn == null) ? null : txn.txn, 237 start, stop, compact, config.getFlags(), end); 238 return compact; 239 } 240 241 /** 242 Return a cursor into the database. 243 <p> 244 @param txn 245 To use a cursor for writing to a transactional database, an explicit 246 transaction must be specified. For read-only access to a transactional 247 database, the transaction may be null. For a non-transactional database, 248 the transaction must be null. 249 <p> 250 To transaction-protect cursor operations, cursors must be opened and closed 251 within the context of a transaction, and the txn parameter specifies the 252 transaction context in which the cursor will be used. 253 <p> 254 @param config 255 The cursor attributes. If null, default attributes are used. 256 <p> 257 @return 258 A database cursor. 259 <p> 260 @throws DatabaseException if a failure occurs. 261 */ 262 public Cursor openCursor(final Transaction txn, CursorConfig config) 263 throws DatabaseException { 264 265 return new Cursor(this, CursorConfig.checkNull(config).openCursor( 266 db, (txn == null) ? null : txn.txn), config); 267 } 268 269 /** 270 Open a sequence in the database. 271 <p> 272 @param txn 273 For a transactional database, an explicit transaction may be specified, or 274 null may be specified to use auto-commit. For a non-transactional 275 database, null must be specified. 276 <p> 277 @param key 278 The key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} of the sequence. 279 <p> 280 @param config 281 The sequence attributes. If null, default attributes are used. 282 <p> 283 @return 284 A sequence handle. 285 <p> 286 @throws DatabaseException if a failure occurs. 287 */ 288 public Sequence openSequence(final Transaction txn, 289 final DatabaseEntry key, 290 final SequenceConfig config) 291 throws DatabaseException { 292 293 return new Sequence(SequenceConfig.checkNull(config).openSequence( 294 db, (txn == null) ? null : txn.txn, key), config); 295 } 296 297 /** 298 Remove the sequence from the database. This method should not be called if 299 there are open handles on this sequence. 300 <p> 301 @param txn 302 For a transactional database, an explicit transaction may be specified, or 303 null may be specified to use auto-commit. For a non-transactional 304 database, null must be specified. 305 <p> 306 @param key 307 The key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} of the sequence. 308 <p> 309 @param config 310 The sequence attributes. If null, default attributes are used. 311 */ 312 public void removeSequence(final Transaction txn, 313 final DatabaseEntry key, 314 SequenceConfig config) 315 throws DatabaseException { 316 317 config = SequenceConfig.checkNull(config); 318 final DbSequence seq = config.openSequence( 319 db, (txn == null) ? null : txn.txn, key); 320 seq.remove((txn == null) ? null : txn.txn, 321 (txn == null && db.get_transactional()) ? 322 DbConstants.DB_AUTO_COMMIT | (config.getAutoCommitNoSync() ? 323 DbConstants.DB_TXN_NOSYNC : 0) : 0); 324 } 325 326 /** 327Return the database's underlying file name. 328<p> 329This method may be called at any time during the life of the application. 330<p> 331@return 332The database's underlying file name. 333 */ 334 public String getDatabaseFile() 335 throws DatabaseException { 336 337 return db.get_filename(); 338 } 339 340 /** 341Return the database name. 342<p> 343This method may be called at any time during the life of the application. 344<p> 345@return 346The database name. 347 */ 348 public String getDatabaseName() 349 throws DatabaseException { 350 351 return db.get_dbname(); 352 } 353 354 /** 355 Return this Database object's configuration. 356 <p> 357 This may differ from the configuration used to open this object if 358 the database existed previously. 359 <p> 360 @return 361 This Database object's configuration. 362 <p> 363 <p> 364@throws DatabaseException if a failure occurs. 365 */ 366 public DatabaseConfig getConfig() 367 throws DatabaseException { 368 369 return new DatabaseConfig(db); 370 } 371 372 /** 373 Change the settings in an existing database handle. 374 <p> 375 @param config The environment attributes. If null, default attributes are used. 376 <p> 377 <p> 378@throws IllegalArgumentException if an invalid parameter was specified. 379<p> 380@throws DatabaseException if a failure occurs. 381 */ 382 public void setConfig(DatabaseConfig config) 383 throws DatabaseException { 384 385 config.configureDatabase(db, getConfig()); 386 } 387 388 /** 389Return the {@link com.sleepycat.db.Environment Environment} handle for the database environment 390 underlying the {@link com.sleepycat.db.Database Database}. 391<p> 392This method may be called at any time during the life of the application. 393<p> 394@return 395The {@link com.sleepycat.db.Environment Environment} handle for the database environment 396 underlying the {@link com.sleepycat.db.Database Database}. 397<p> 398<p> 399@throws DatabaseException if a failure occurs. 400 */ 401 public Environment getEnvironment() 402 throws DatabaseException { 403 404 return db.get_env().wrapper; 405 } 406 407 /** 408Return the handle for the cache file underlying the database. 409<p> 410This method may be called at any time during the life of the application. 411<p> 412@return 413The handle for the cache file underlying the database. 414<p> 415<p> 416@throws DatabaseException if a failure occurs. 417 */ 418 public CacheFile getCacheFile() 419 throws DatabaseException { 420 421 return new CacheFile(db.get_mpf()); 422 } 423 424 /** 425 <p> 426Append the key/data pair to the end of the database. 427<p> 428The underlying database must be a Queue or Recno database. The record 429number allocated to the record is returned in the key parameter. 430<p> 431There is a minor behavioral difference between the Recno and Queue 432access methods this method. If a transaction enclosing this method 433aborts, the record number may be decremented (and later reallocated by 434a subsequent operation) in the Recno access method, but will not be 435decremented or reallocated in the Queue access method. 436<p> 437It may be useful to modify the stored data based on the generated key. 438If a callback function is specified using {@link com.sleepycat.db.DatabaseConfig#setRecordNumberAppender DatabaseConfig.setRecordNumberAppender}, it will be called after the record number has 439been selected, but before the data has been stored. 440<p> 441@param txn 442For a transactional database, an explicit transaction may be specified, or null 443may be specified to use auto-commit. For a non-transactional database, null 444must be specified. 445<p> 446@param key the key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} operated on. 447<p> 448@param data the data {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} stored. 449<p> 450<p> 451<p> 452@throws DeadlockException if the operation was selected to resolve a 453deadlock. 454<p> 455@throws DatabaseException if a failure occurs. 456 */ 457 public OperationStatus append(final Transaction txn, 458 final DatabaseEntry key, 459 final DatabaseEntry data) 460 throws DatabaseException { 461 462 return OperationStatus.fromInt( 463 db.put((txn == null) ? null : txn.txn, key, data, 464 DbConstants.DB_APPEND | ((txn == null) ? autoCommitFlag : 0))); 465 } 466 467 /** 468 Return the record number and data from the available record closest to 469the head of the queue, and delete the record. The record number will be 470returned in the <code>key</code> parameter, and the data will be returned 471in the <code>data</code> parameter. A record is available if it is not 472deleted and is not currently locked. The underlying database must be 473of type Queue for this method to be called. 474<p> 475@param txn 476For a transactional database, an explicit transaction may be specified to 477transaction-protect the operation, or null may be specified to perform the 478operation without transaction protection. For a non-transactional database, 479null must be specified. 480@param key the key 481returned as output. Its byte array does not need to be initialized by the 482caller. 483@param data the data 484returned as output. Its byte array does not need to be initialized by the 485caller. 486@param wait 487if there is no record available, this parameter determines whether the 488method waits for one to become available, or returns immediately with 489status <code>NOTFOUND</code>. 490<p> 491@return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if no matching key/data pair is 492found; {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 493<p> 494<p> 495@throws DeadlockException if the operation was selected to resolve a 496deadlock. 497<p> 498@throws IllegalArgumentException if an invalid parameter was specified. 499<p> 500@throws DatabaseException if a failure occurs. 501 */ 502 public OperationStatus consume(final Transaction txn, 503 final DatabaseEntry key, 504 final DatabaseEntry data, 505 final boolean wait) 506 throws DatabaseException { 507 508 return OperationStatus.fromInt( 509 db.get((txn == null) ? null : txn.txn, 510 key, data, 511 (wait ? DbConstants.DB_CONSUME_WAIT : DbConstants.DB_CONSUME) | 512 ((txn == null) ? autoCommitFlag : 0))); 513 } 514 515 /** 516 Remove key/data pairs from the database. 517 <p> 518 The key/data pair associated with the specified key is discarded 519 from the database. In the presence of duplicate key values, all 520 records associated with the designated key will be discarded. 521 <p> 522 The key/data pair is also deleted from any associated secondary 523 databases. 524 <p> 525 @param txn 526For a transactional database, an explicit transaction may be specified, or null 527may be specified to use auto-commit. For a non-transactional database, null 528must be specified. 529 <p> 530 @param key the key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} operated on. 531 <p> 532 @return 533 The method will return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if the 534 specified key is not found in the database; 535 The method will return {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the 536 database is a Queue or Recno database and the specified key exists, 537 but was never explicitly created by the application or was later 538 deleted; 539 otherwise the method will return {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 540 <p> 541 <p> 542@throws DeadlockException if the operation was selected to resolve a 543deadlock. 544<p> 545@throws DatabaseException if a failure occurs. 546 */ 547 public OperationStatus delete(final Transaction txn, 548 final DatabaseEntry key) 549 throws DatabaseException { 550 551 return OperationStatus.fromInt( 552 db.del((txn == null) ? null : txn.txn, key, 553 ((txn == null) ? autoCommitFlag : 0))); 554 } 555 556 /** 557 Remove key/data pairs from the database. 558 <p> 559 The key/data pair associated with the specified key is discarded 560 from the database. In the presence of duplicate key values, all 561 records associated with the designated key will be discarded. 562 <p> 563 The key/data pair is also deleted from any associated secondary 564 databases. 565 <p> 566 @param txn 567For a transactional database, an explicit transaction may be specified, or null 568may be specified to use auto-commit. For a non-transactional database, null 569must be specified. 570 <p> 571 @param keys the set of keys {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} operated on. 572 <p> 573 @return 574 The method will return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if the 575 specified key is not found in the database; 576 The method will return {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the 577 database is a Queue or Recno database and the specified key exists, 578 but was never explicitly created by the application or was later 579 deleted; 580 otherwise the method will return {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 581 <p> 582 <p> 583@throws DeadlockException if the operation was selected to resolve a 584deadlock. 585<p> 586@throws DatabaseException if a failure occurs. 587 */ 588 public OperationStatus deleteMultiple(final Transaction txn, 589 final MultipleEntry keys) 590 throws DatabaseException { 591 592 return OperationStatus.fromInt( 593 db.del((txn == null) ? null : txn.txn, keys, 594 DbConstants.DB_MULTIPLE | 595 ((txn == null) ? autoCommitFlag : 0))); 596 } 597 598 /** 599 Checks if the specified key appears in the database. 600<p> 601@param txn 602For a transactional database, an explicit transaction may be specified to 603transaction-protect the operation, or null may be specified to perform the 604operation without transaction protection. For a non-transactional database, 605null must be specified. 606<p> 607@param key the key 608used as input. It must be initialized with a non-null byte array by the 609caller. 610<p> 611@return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if no matching key/data pair is 612found; {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 613<p> 614<p> 615@throws DeadlockException if the operation was selected to resolve a 616deadlock. 617<p> 618@throws IllegalArgumentException if an invalid parameter was specified. 619<p> 620@throws DatabaseException if a failure occurs. 621 */ 622 public OperationStatus exists(final Transaction txn, 623 final DatabaseEntry key) 624 throws DatabaseException { 625 626 return OperationStatus.fromInt( 627 db.exists((txn == null) ? null : txn.txn, key, 628 ((txn == null) ? autoCommitFlag : 0))); 629 } 630 631 /** 632 Retrieves the key/data pair with the given key. If the matching key has 633duplicate values, the first data item in the set of duplicates is returned. 634Retrieval of duplicates requires the use of {@link Cursor} operations. 635<p> 636@param txn 637For a transactional database, an explicit transaction may be specified to 638transaction-protect the operation, or null may be specified to perform the 639operation without transaction protection. For a non-transactional database, 640null must be specified. 641<p> 642@param key the key 643used as input. It must be initialized with a non-null byte array by the 644caller. 645<p> 646<p> 647@param data the data 648returned as output. Its byte array does not need to be initialized by the 649caller. 650<p> 651@param lockMode the locking attributes; if null, default attributes are used. 652<p> 653@return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if no matching key/data pair is 654found; {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 655<p> 656<p> 657@throws DeadlockException if the operation was selected to resolve a 658deadlock. 659<p> 660@throws IllegalArgumentException if an invalid parameter was specified. 661<p> 662@throws DatabaseException if a failure occurs. 663 */ 664 public OperationStatus get(final Transaction txn, 665 final DatabaseEntry key, 666 final DatabaseEntry data, 667 final LockMode lockMode) 668 throws DatabaseException { 669 670 return OperationStatus.fromInt( 671 db.get((txn == null) ? null : txn.txn, 672 key, data, 673 LockMode.getFlag(lockMode) | 674 ((data == null) ? 0 : data.getMultiFlag()))); 675 } 676 677 /** 678 Return an estimate of the proportion of keys in the database less 679 than, equal to, and greater than the specified key. 680 <p> 681 The underlying database must be of type Btree. 682 <p> 683 This method does not retain the locks it acquires for the life of 684 the transaction, so estimates are not repeatable. 685 <p> 686 @param key 687 The key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} being compared. 688 <p> 689 @param txn 690For a transactional database, an explicit transaction may be specified to 691transaction-protect the operation, or null may be specified to perform the 692operation without transaction protection. For a non-transactional database, 693null must be specified. 694 <p> 695 @return 696 An estimate of the proportion of keys in the database less than, 697 equal to, and greater than the specified key. 698 <p> 699 <p> 700@throws DeadlockException if the operation was selected to resolve a 701deadlock. 702<p> 703@throws DatabaseException if a failure occurs. 704 */ 705 public KeyRange getKeyRange(final Transaction txn, 706 final DatabaseEntry key) 707 throws DatabaseException { 708 709 final KeyRange range = new KeyRange(); 710 db.key_range((txn == null) ? null : txn.txn, key, range, 0); 711 return range; 712 } 713 714 /** 715 Retrieves the key/data pair with the given key and data value, that is, both 716the key and data items must match. 717<p> 718@param txn 719For a transactional database, an explicit transaction may be specified to 720transaction-protect the operation, or null may be specified to perform the 721operation without transaction protection. For a non-transactional database, 722null must be specified. 723@param key the key 724used as input. It must be initialized with a non-null byte array by the 725caller. 726@param data the data 727used as input. It must be initialized with a non-null byte array by the 728caller. 729<p> 730@param lockMode the locking attributes; if null, default attributes are used. 731<p> 732@return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if no matching key/data pair is 733found; {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 734<p> 735<p> 736@throws DeadlockException if the operation was selected to resolve a 737deadlock. 738<p> 739@throws IllegalArgumentException if an invalid parameter was specified. 740<p> 741@throws DatabaseException if a failure occurs. 742 */ 743 public OperationStatus getSearchBoth(final Transaction txn, 744 final DatabaseEntry key, 745 final DatabaseEntry data, 746 final LockMode lockMode) 747 throws DatabaseException { 748 749 return OperationStatus.fromInt( 750 db.get((txn == null) ? null : txn.txn, 751 key, data, 752 DbConstants.DB_GET_BOTH | 753 LockMode.getFlag(lockMode) | 754 ((data == null) ? 0 : data.getMultiFlag()))); 755 } 756 757 /** 758 Retrieves the key/data pair associated with the specific numbered record of the database. 759<p> 760The data field of the specified key must be a byte array containing a 761record number, as described in {@link com.sleepycat.db.DatabaseEntry DatabaseEntry}. This determines 762the record to be retrieved. 763<p> 764For this method to be called, the underlying database must be of type 765Btree, and it must have been configured to support record numbers. 766<p> 767If this method fails for any reason, the position of the cursor will be 768unchanged. 769@throws NullPointerException if a DatabaseEntry parameter is null or 770does not contain a required non-null byte array. 771<p> 772@throws DeadlockException if the operation was selected to resolve a 773deadlock. 774<p> 775@throws IllegalArgumentException if an invalid parameter was specified. 776<p> 777@throws DatabaseException if a failure occurs. 778<p> 779@param key the key 780returned as output. Its byte array does not need to be initialized by the 781caller. 782@param data the data 783returned as output. Multiple results can be retrieved by passing an object 784that is a subclass of {@link com.sleepycat.db.MultipleEntry MultipleEntry}, otherwise its byte array does not 785need to be initialized by the caller. 786@param lockMode the locking attributes; if null, default attributes are used. 787@return {@link com.sleepycat.db.OperationStatus#NOTFOUND OperationStatus.NOTFOUND} if no matching key/data pair is 788found; {@link com.sleepycat.db.OperationStatus#KEYEMPTY OperationStatus.KEYEMPTY} if the database is a Queue or Recno database and the specified key exists, but was never explicitly created by the application or was later deleted; otherwise, {@link com.sleepycat.db.OperationStatus#SUCCESS OperationStatus.SUCCESS}. 789 */ 790 public OperationStatus getSearchRecordNumber(final Transaction txn, 791 final DatabaseEntry key, 792 final DatabaseEntry data, 793 final LockMode lockMode) 794 throws DatabaseException { 795 796 return OperationStatus.fromInt( 797 db.get((txn == null) ? null : txn.txn, 798 key, data, 799 DbConstants.DB_SET_RECNO | 800 LockMode.getFlag(lockMode) | 801 ((data == null) ? 0 : data.getMultiFlag()))); 802 } 803 804 /** 805 <p> 806Store the key/data pair into the database. 807<p> 808If the key already appears in the database and duplicates are not 809configured, the existing key/data pair will be replaced. If the key 810already appears in the database and sorted duplicates are configured, 811the new data value is inserted at the correct sorted location. 812If the key already appears in the database and unsorted duplicates are 813configured, the new data value is appended at the end of the duplicate 814set. 815<p> 816@param txn 817For a transactional database, an explicit transaction may be specified, or null 818may be specified to use auto-commit. For a non-transactional database, null 819must be specified. 820<p> 821@param key the key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} operated on. 822<p> 823@param data the data {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} stored. 824<p> 825<p> 826<p> 827@throws DeadlockException if the operation was selected to resolve a 828deadlock. 829<p> 830@throws DatabaseException if a failure occurs. 831 */ 832 public OperationStatus put(final Transaction txn, 833 final DatabaseEntry key, 834 final DatabaseEntry data) 835 throws DatabaseException { 836 837 return OperationStatus.fromInt( 838 db.put((txn == null) ? null : txn.txn, 839 key, data, 840 ((txn == null) ? autoCommitFlag : 0))); 841 } 842 843 /** 844 <p> 845Store a set of key/data pairs into the database. 846<p> 847The key and data parameters must contain corresponding key/data pairs. That is 848the first entry in the multiple key is inserted with the first entry from the 849data parameter. Similarly for all remaining keys in the set. 850<p> 851This method may not be called on databases configured with unsorted duplicates. 852<p> 853@param txn 854For a transactional database, an explicit transaction may be specified, or null 855may be specified to use auto-commit. For a non-transactional database, null 856must be specified. 857<p> 858@param key the set of keys {@link com.sleepycat.db.MultipleEntry MultipleEntry} operated on. 859<p> 860@param data the set of data {@link com.sleepycat.db.MultipleEntry MultipleEntry} stored. 861<p> 862@param overwrite if this flag is true and any of the keys already exist in the database, they will be replaced. Otherwise a KEYEXIST error will be returned. 863<p> 864@return 865If any of the key/data pairs already appear in the database, this method will 866return {@link com.sleepycat.db.OperationStatus#KEYEXIST OperationStatus.KEYEXIST}. 867<p> 868<p> 869@throws DeadlockException if the operation was selected to resolve a 870deadlock. 871<p> 872@throws DatabaseException if a failure occurs. 873 */ 874 public OperationStatus putMultiple(final Transaction txn, 875 final MultipleEntry key, 876 final MultipleEntry data, 877 final boolean overwrite) 878 throws DatabaseException { 879 880 return OperationStatus.fromInt( 881 db.put((txn == null) ? null : txn.txn, 882 key, data, 883 DbConstants.DB_MULTIPLE | 884 (overwrite ? DbConstants.DB_OVERWRITE : 0) | 885 ((txn == null) ? autoCommitFlag : 0))); 886 } 887 888 /** 889 <p> 890Store a set of key/data pairs into the database. 891<p> 892This method may not be called on databases configured with unsorted duplicates. 893<p> 894@param txn 895For a transactional database, an explicit transaction may be specified, or null 896may be specified to use auto-commit. For a non-transactional database, null 897must be specified. 898<p> 899@param key the key and data sets {@link com.sleepycat.db.MultipleEntry MultipleEntry} operated on. 900<p> 901@param overwrite if this flag is true and any of the keys already exist in the database, they will be replaced. Otherwise a KEYEXIST error will be returned. 902<p> 903@return 904If any of the key/data pairs already appear in the database, this method will 905return {@link com.sleepycat.db.OperationStatus#KEYEXIST OperationStatus.KEYEXIST}. 906<p> 907<p> 908@throws DeadlockException if the operation was selected to resolve a 909deadlock. 910<p> 911@throws DatabaseException if a failure occurs. 912 */ 913 public OperationStatus putMultipleKey(final Transaction txn, 914 final MultipleEntry key, 915 final boolean overwrite) 916 throws DatabaseException { 917 918 return OperationStatus.fromInt( 919 db.put((txn == null) ? null : txn.txn, 920 key, null, 921 DbConstants.DB_MULTIPLE_KEY | 922 (overwrite ? DbConstants.DB_OVERWRITE : 0) | 923 ((txn == null) ? autoCommitFlag : 0))); 924 } 925 926 /** 927 <p> 928Store the key/data pair into the database if it does not already appear 929in the database. 930<p> 931This method may only be called if the underlying database has been 932configured to support sorted duplicates. 933(This method may not be specified to the Queue or Recno access methods.) 934<p> 935@param txn 936For a transactional database, an explicit transaction may be specified, or null 937may be specified to use auto-commit. For a non-transactional database, null 938must be specified. 939<p> 940@param key the key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} operated on. 941<p> 942@param data the data {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} stored. 943<p> 944@return 945If the key/data pair already appears in the database, this method will 946return {@link com.sleepycat.db.OperationStatus#KEYEXIST OperationStatus.KEYEXIST}. 947<p> 948<p> 949@throws DeadlockException if the operation was selected to resolve a 950deadlock. 951<p> 952@throws DatabaseException if a failure occurs. 953 */ 954 public OperationStatus putNoDupData(final Transaction txn, 955 final DatabaseEntry key, 956 final DatabaseEntry data) 957 throws DatabaseException { 958 959 return OperationStatus.fromInt( 960 db.put((txn == null) ? null : txn.txn, 961 key, data, 962 DbConstants.DB_NODUPDATA | 963 ((txn == null) ? autoCommitFlag : 0))); 964 } 965 966 /** 967 <p> 968Store the key/data pair into the database if the key does not already 969appear in the database. 970<p> 971This method will fail if the key already exists in the database, even 972if the database supports duplicates. 973<p> 974@param txn 975For a transactional database, an explicit transaction may be specified, or null 976may be specified to use auto-commit. For a non-transactional database, null 977must be specified. 978<p> 979@param key the key {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} operated on. 980<p> 981@param data the data {@link com.sleepycat.db.DatabaseEntry DatabaseEntry} stored. 982<p> 983@return 984If the key already appears in the database, this method will return 985{@link com.sleepycat.db.OperationStatus#KEYEXIST OperationStatus.KEYEXIST}. 986<p> 987<p> 988@throws DeadlockException if the operation was selected to resolve a 989deadlock. 990<p> 991@throws DatabaseException if a failure occurs. 992 */ 993 public OperationStatus putNoOverwrite(final Transaction txn, 994 final DatabaseEntry key, 995 final DatabaseEntry data) 996 throws DatabaseException { 997 998 return OperationStatus.fromInt( 999 db.put((txn == null) ? null : txn.txn, 1000 key, data, 1001 DbConstants.DB_NOOVERWRITE | 1002 ((txn == null) ? autoCommitFlag : 0))); 1003 } 1004 1005 /** 1006 Creates a specialized join cursor for use in performing equality or 1007 natural joins on secondary indices. 1008 <p> 1009 Each cursor in the <code>cursors</code> array must have been 1010 initialized to refer to the key on which the underlying database should 1011 be joined. Typically, this initialization is done by calling 1012 {@link Cursor#getSearchKey Cursor.getSearchKey}. 1013 <p> 1014 Once the cursors have been passed to this method, they should not be 1015 accessed or modified until the newly created join cursor has been 1016 closed, or else inconsistent results may be returned. However, the 1017 position of the cursors will not be changed by this method or by the 1018 methods of the join cursor. 1019 <p> 1020 @param cursors an array of cursors associated with this primary 1021 database. 1022 <p> 1023 @param config The join attributes. If null, default attributes are used. 1024 <p> 1025 @return 1026 a specialized cursor that returns the results of the equality join 1027 operation. 1028 <p> 1029 @throws DatabaseException if a failure occurs. 1030 <p> 1031 @see JoinCursor 1032 */ 1033 public JoinCursor join(final Cursor[] cursors, JoinConfig config) 1034 throws DatabaseException { 1035 1036 config = JoinConfig.checkNull(config); 1037 1038 final Dbc[] dbcList = new Dbc[cursors.length]; 1039 for (int i = 0; i < cursors.length; i++) 1040 dbcList[i] = (cursors[i] == null) ? null : cursors[i].dbc; 1041 1042 return new JoinCursor(this, 1043 db.join(dbcList, config.getFlags()), config); 1044 } 1045 1046 /** 1047 Empty the database, discarding all records it contains. 1048 <p> 1049 When called on a database configured with secondary indices, this 1050 method truncates the primary database and all secondary indices. If 1051 configured to return a count of the records discarded, the returned 1052 count is the count of records discarded from the primary database. 1053 <p> 1054 It is an error to call this method on a database with open cursors. 1055 <p> 1056 @param txn 1057 For a transactional database, an explicit transaction may be specified, or 1058 null may be specified to use auto-commit. For a non-transactional 1059 database, null must be specified. 1060 <p> 1061 @param countRecords 1062 If true, count and return the number of records discarded. 1063 <p> 1064 @return 1065 The number of records discarded, or -1 if returnCount is false. 1066 <p> 1067 @throws DeadlockException if the operation was selected to resolve a 1068 deadlock. 1069 <p> 1070 @throws DatabaseException if a failure occurs. 1071 */ 1072 public int truncate(final Transaction txn, boolean countRecords) 1073 throws DatabaseException { 1074 1075 // XXX: implement countRecords in C 1076 int count = db.truncate((txn == null) ? null : txn.txn, 1077 ((txn == null) ? autoCommitFlag : 0)); 1078 1079 return countRecords ? count : -1; 1080 } 1081 1082 /** 1083 Return database statistics. 1084 <p> 1085 If this method has not been configured to avoid expensive operations 1086 (using the {@link com.sleepycat.db.StatsConfig#setFast StatsConfig.setFast} method), it will access 1087 some of or all the pages in the database, incurring a severe 1088 performance penalty as well as possibly flushing the underlying 1089 buffer pool. 1090 <p> 1091 In the presence of multiple threads or processes accessing an active 1092 database, the information returned by this method may be out-of-date. 1093 <p> 1094 If the database was not opened read-only and this method was not 1095 configured using the {@link com.sleepycat.db.StatsConfig#setFast StatsConfig.setFast} method, cached 1096 key and record numbers will be updated after the statistical 1097 information has been gathered. 1098 <p> 1099 @param txn 1100 For a transactional database, an explicit transaction may be specified to 1101 transaction-protect the operation, or null may be specified to perform the 1102 operation without transaction protection. For a non-transactional 1103 database, null must be specified. 1104 <p> 1105 @param config 1106 The statistics returned; if null, default statistics are returned. 1107 <p> 1108 @return 1109 Database statistics. 1110 <p> 1111 @throws DeadlockException if the operation was selected to resolve a 1112 deadlock. 1113 <p> 1114 @throws DatabaseException if a failure occurs. 1115 */ 1116 public DatabaseStats getStats(final Transaction txn, StatsConfig config) 1117 throws DatabaseException { 1118 1119 return (DatabaseStats)db.stat((txn == null) ? null : txn.txn, 1120 StatsConfig.checkNull(config).getFlags()); 1121 } 1122 1123 /** 1124 <p> 1125Remove a database. 1126<p> 1127If no database is specified, the underlying file specified is removed. 1128<p> 1129Applications should never remove databases with open {@link com.sleepycat.db.Database Database} 1130handles, or in the case of removing a file, when any database in the 1131file has an open handle. For example, some architectures do not permit 1132the removal of files with open system handles. On these architectures, 1133attempts to remove databases currently in use by any thread of control 1134in the system may fail. 1135<p> 1136If the database was opened within a database environment, the 1137environment variable DB_HOME may be used as the path of the database 1138environment home. 1139<p> 1140This method is affected by any database directory specified with 1141{@link com.sleepycat.db.EnvironmentConfig#addDataDir EnvironmentConfig.addDataDir}, or by setting the "set_data_dir" 1142string in the database environment's DB_CONFIG file. 1143<p> 1144The {@link com.sleepycat.db.Database Database} handle may not be accessed 1145again after this method is called, regardless of this method's success 1146or failure. 1147<p> 1148@param fileName 1149The physical file which contains the database to be removed. 1150On Windows platforms, this argument will be interpreted as a UTF-8 1151string, which is equivalent to ASCII for Latin characters. 1152<p> 1153@param databaseName 1154The database to be removed. 1155<p> 1156@param config The database remove attributes. If null, default attributes are used. 1157<p> 1158<p> 1159@throws DatabaseException if a failure occurs. 1160 */ 1161 public static void remove(final String fileName, 1162 final String databaseName, 1163 DatabaseConfig config) 1164 throws DatabaseException, java.io.FileNotFoundException { 1165 1166 final Db db = DatabaseConfig.checkNull(config).createDatabase(null); 1167 db.remove(fileName, databaseName, 0); 1168 } 1169 1170 /** 1171 <p> 1172Rename a database. 1173<p> 1174If no database name is specified, the underlying file specified is 1175renamed, incidentally renaming all of the databases it contains. 1176<p> 1177Applications should never rename databases that are currently in use. 1178If an underlying file is being renamed and logging is currently enabled 1179in the database environment, no database in the file may be open when 1180this method is called. In particular, some architectures do not permit 1181renaming files with open handles. On these architectures, attempts to 1182rename databases that are currently in use by any thread of control in 1183the system may fail. 1184<p> 1185If the database was opened within a database environment, the 1186environment variable DB_HOME may be used as the path of the database 1187environment home. 1188<p> 1189This method is affected by any database directory specified with 1190{@link com.sleepycat.db.EnvironmentConfig#addDataDir EnvironmentConfig.addDataDir}, or by setting the "set_data_dir" 1191string in the database environment's DB_CONFIG file. 1192<p> 1193The {@link com.sleepycat.db.Database Database} handle may not be accessed 1194again after this method is called, regardless of this method's success 1195or failure. 1196<p> 1197@param fileName 1198The physical file which contains the database to be renamed. 1199On Windows platforms, this argument will be interpreted as a UTF-8 1200string, which is equivalent to ASCII for Latin characters. 1201<p> 1202@param oldDatabaseName 1203The database to be renamed. 1204<p> 1205@param newDatabaseName 1206The new name of the database or file. 1207<p> 1208@param config The database rename attributes. If null, default attributes are used. 1209<p> 1210<p> 1211@throws DatabaseException if a failure occurs. 1212 */ 1213 public static void rename(final String fileName, 1214 final String oldDatabaseName, 1215 final String newDatabaseName, 1216 DatabaseConfig config) 1217 throws DatabaseException, java.io.FileNotFoundException { 1218 1219 final Db db = DatabaseConfig.checkNull(config).createDatabase(null); 1220 db.rename(fileName, oldDatabaseName, newDatabaseName, 0); 1221 } 1222 1223 /** 1224 Sorts a DatabaseEntry with multiple matching key/data pairs. 1225 <p> 1226 If specified, the application specific btree comparison and duplicate 1227 comparison functions will be used. 1228 <p> 1229 @param entries 1230 A MultipleKeyDataEntry that contains matching pairs of key/data items, 1231 the sorted entries will be returned in the original entries object. 1232 */ 1233 public static void sortMultipleKeyData(MultipleKeyDataEntry entries) 1234 throws DatabaseException { 1235 Database.sortMultiple(entries, null); 1236 } 1237 1238 /** 1239 Sorts a DatabaseEntry with multiple key or data pairs. 1240 <p> 1241 If specified, the application specific btree comparison function will be 1242 used. 1243 <p> 1244 @param entries 1245 A MultipleDataEntry that contains multiple key or data items, 1246 the sorted entries will be returned in the original entries object. 1247 */ 1248 public static void sortMultipleKeyOrData(MultipleDataEntry entries) 1249 throws DatabaseException { 1250 Database.sortMultiple(entries, null); 1251 } 1252 1253 /** 1254 Sorts two DatabaseEntry objects with multiple key and data pairs. 1255 <p> 1256 If specified, the application specific btree comparison and duplicate 1257 comparison functions will be used. 1258 <p> 1259 The key and data parameters must contain "pairs" of items. That is the n-th 1260 entry in keys corresponds to the n-th entry in datas. 1261 @param keys 1262 A MultipleDataEntry that contains multiple key items, the sorted entries 1263 will be returned in the original entries object. 1264 @param datas 1265 A MultipleDataEntry that contains multiple data items, the sorted entries 1266 will be returned in the original entries object. 1267 */ 1268 public static void sortMultipleKeyAndData( 1269 MultipleDataEntry keys, MultipleDataEntry datas) 1270 throws DatabaseException { 1271 Database.sortMultiple(keys, datas); 1272 } 1273 1274 private static void sortMultiple(MultipleEntry keys, MultipleEntry datas) 1275 throws DatabaseException { 1276 final Db db = DatabaseConfig.DEFAULT.createDatabase(null); 1277 db.sort_multiple(keys, datas); 1278 db.close(0); 1279 } 1280 1281 1282 /** 1283 Flush any cached information to disk. 1284 <p> 1285 If the database is in memory only, this method has no effect and 1286 will always succeed. 1287 <p> 1288 <b>It is important to understand that flushing cached information to 1289 disk only minimizes the window of opportunity for corrupted data.</b> 1290 <p> 1291 Although unlikely, it is possible for database corruption to happen 1292 if a system or application crash occurs while writing data to the 1293 database. To ensure that database corruption never occurs, 1294 applications must either: use transactions and logging with 1295 automatic recovery; use logging and application-specific recovery; 1296 or edit a copy of the database, and once all applications using the 1297 database have successfully closed the copy of the database, 1298 atomically replace the original database with the updated copy. 1299 <p> 1300 <p> 1301@throws DatabaseException if a failure occurs. 1302 */ 1303 public void sync() 1304 throws DatabaseException { 1305 1306 db.sync(0); 1307 } 1308 1309 /** 1310 Upgrade all of the databases included in the specified file. 1311 <p> 1312 If no upgrade is necessary, always returns success. 1313 <p> 1314 <b> 1315 Database upgrades are done in place and are destructive. For example, 1316 if pages need to be allocated and no disk space is available, the 1317 database may be left corrupted. Backups should be made before databases 1318 are upgraded. 1319 </b> 1320 <p> 1321 <b> 1322 The following information is only meaningful when upgrading databases 1323 from releases before the Berkeley DB 3.1 release: 1324 </b> 1325 <p> 1326 As part of the upgrade from the Berkeley DB 3.0 release to the 3.1 1327 release, the on-disk format of duplicate data items changed. To 1328 correctly upgrade the format requires applications to specify 1329 whether duplicate data items in the database are sorted or not. 1330 Configuring the database object to support sorted duplicates by the 1331 {@link com.sleepycat.db.DatabaseConfig#setSortedDuplicates DatabaseConfig.setSortedDuplicates} method informs this 1332 method that the duplicates are sorted; otherwise they are assumed 1333 to be unsorted. Incorrectly specifying this configuration 1334 information may lead to database corruption. 1335 <p> 1336 Further, because this method upgrades a physical file (including all 1337 the databases it contains), it is not possible to use this method 1338 to upgrade files in which some of the databases it includes have 1339 sorted duplicate data items, and some of the databases it includes 1340 have unsorted duplicate data items. If the file does not have more 1341 than a single database, if the databases do not support duplicate 1342 data items, or if all of the databases that support duplicate data 1343 items support the same style of duplicates (either sorted or 1344 unsorted), this method will work correctly as long as the duplicate 1345 configuration is correctly specified. Otherwise, the file cannot 1346 be upgraded using this method; it must be upgraded manually by 1347 dumping and reloading the databases. 1348 <p> 1349 Unlike all other database operations, upgrades may only be done on 1350 a system with the same byte-order as the database. 1351 <p> 1352 @param fileName 1353 The physical file containing the databases to be upgraded. 1354 <p> 1355 <p> 1356@throws DatabaseException if a failure occurs. 1357 */ 1358 public static void upgrade(final String fileName, 1359 DatabaseConfig config) 1360 throws DatabaseException, java.io.FileNotFoundException { 1361 1362 final Db db = DatabaseConfig.checkNull(config).createDatabase(null); 1363 db.upgrade(fileName, 1364 config.getSortedDuplicates() ? DbConstants.DB_DUPSORT : 0); 1365 db.close(0); 1366 } 1367 1368 /** 1369 Return if all of the databases in a file are uncorrupted. 1370 <p> 1371 This method optionally outputs the databases' key/data pairs to a 1372 file stream. 1373 <p> 1374 <b> 1375 This method does not perform any locking, even in database 1376 environments are configured with a locking subsystem. As such, it 1377 should only be used on files that are not being modified by another 1378 thread of control. 1379 </b> 1380 <p> 1381 This method may not be called after the database is opened. 1382 <p> 1383 If the database was opened within a database environment, the 1384environment variable DB_HOME may be used as the path of the database 1385environment home. 1386<p> 1387This method is affected by any database directory specified with 1388{@link com.sleepycat.db.EnvironmentConfig#addDataDir EnvironmentConfig.addDataDir}, or by setting the "set_data_dir" 1389string in the database environment's DB_CONFIG file. 1390 <p> 1391 The {@link com.sleepycat.db.Database Database} handle may not be accessed 1392again after this method is called, regardless of this method's success 1393or failure. 1394 <p> 1395 @param fileName 1396 The physical file in which the databases to be verified are found. 1397 <p> 1398 @param databaseName 1399 The database in the file on which the database checks for btree and 1400 duplicate sort order and for hashing are to be performed. This 1401 parameter should be set to null except when the operation has been 1402 been configured by {@link com.sleepycat.db.VerifyConfig#setOrderCheckOnly VerifyConfig.setOrderCheckOnly}. 1403 <p> 1404 @param dumpStream 1405 An optional file stream to which the databases' key/data pairs are 1406 written. This parameter should be set to null except when the 1407 operation has been been configured by {@link com.sleepycat.db.VerifyConfig#setSalvage VerifyConfig.setSalvage}. 1408 <p> 1409 @param verifyConfig The verify operation attributes. If null, default attributes are used. 1410 <p> 1411 @param dbConfig The database attributes. If null, default attributes are used. 1412 <p> 1413 @return 1414 True, if all of the databases in the file are uncorrupted. If this 1415 method returns false, and the operation was configured by 1416 {@link com.sleepycat.db.VerifyConfig#setSalvage VerifyConfig.setSalvage}, all of the key/data pairs in the 1417 file may not have been successfully output. 1418 <p> 1419 <p> 1420@throws DatabaseException if a failure occurs. 1421 */ 1422 public static boolean verify(final String fileName, 1423 final String databaseName, 1424 final java.io.PrintStream dumpStream, 1425 VerifyConfig verifyConfig, 1426 DatabaseConfig dbConfig) 1427 throws DatabaseException, java.io.FileNotFoundException { 1428 1429 final Db db = DatabaseConfig.checkNull(dbConfig).createDatabase(null); 1430 return db.verify(fileName, databaseName, dumpStream, 1431 VerifyConfig.checkNull(verifyConfig).getFlags()); 1432 } 1433} 1434