Berkeley DB Java Edition
Release Notes

1.7.0, November 29, 2004

These release notes contain:

Overview

Berkeley DB Java Edition (JE) is a 100% pure Java implementation of Berkeley DB. It implements a transactional store model based on a B-Tree access method.

JE's capabilities and features are described in the Getting Started with Berkeley DB Java Edition guide. That document also introduces the JE API set. For a complete description of the JE API set, see the Javadoc. For a description of how to use JE and the Sleepycat Java Collections API, see the collections tutorial.

New in this Release

This is the 1.7.0 release of Berkeley DB Java Edition. This release contains the performance enhancements and bug fixes since release 1.5.3 of the product. Key changes are described below; the complete list of changes can be found in the change log page for this release.

Note: If you are using Mac OS X, please be aware of the following issue. Java version 1.4.2 on Mac OS X reports the wrong value for Runtime.maxMemory. JE calculates the default cache size as a percentage of maxMemory.  Because of this, for Java 1.4.2 on Mac OS X only, JE will assume that the Java maxMemory value is 64 MB.  With the default je.maxMemoryPercent configuration parameter (60%) the default JE cache size will be approximately 38 MB.  This default is fixed -- it does not change if the Java memory size is different than 64 MB.  To specify a different JE cache size, you must explicitly set the je.maxMemory configuration property.  The je.maxMemory property can be specified in the je.properties file or by calling EnvironmentConfig.setCacheSize.

Log File On-Disk Format Changes:

  1. JE 1.7.0 has moved to on-disk file format 2.

    The change is forward compatible in that JE files created with release 1.5.3 and earlier can be read when opened with JE 1.7.0.  The change is not backwards compatible in that files created with JE 1.7.0 cannot be read by earlier releases. Note that if a 1.5.3 environment is opened read/write, a new log file is written by JE 1.7.0 and the environment can no longer be read by earlier releases.

New Features:

  1. Added a new transaction commit mode. Previously, JE had the ability to commit transactions synchronously or asynchronously (nosync mode).  A synchronous commit is one where JE guarantees full transaction durability by writing and flushing JE log buffers to disk at commit time. "Write" means to move bytes from the JVM's buffers to the operating system's buffers, using the java.nio.channel.FileChannel.write() call and "flush" means to force the operating system's buffers to durable storage using the java.nio.channel.FileChannel.force() call.

    Alternatively, the user could commit transactions in "noSync" mode which does not write or flush log buffers and therefore has better performance, but carries a greater risk of losing the transaction if the JVM crashes.

    JE 1.7.0 has a new "commitWriteNoSync()" mode which does write but does not flush log buffers at commit time. The transaction will be durable if the JVM crashes, but will not be durable if the OS crashes. CommitWriteNoSync is faster than a synchronous commit and slower than a asynchronous commit. Synchronous, writeNoSync, and noSync modes can be specified through EnvironmentMutableConfig, TransactionConfig, or through Transaction commit(), commitWriteNoSync(), commitNoSync(). [#11131]

API Changes:

  1. The environment cache size properties (je.maxMemory and je.maxMemoryPercent) can now be changed by the application after opening the environment. [#11337]

  2. Database.truncate() is deprecated and a new method Environment.truncateDatabase() is added.

    Previous versions of JE had a bug where the results of a Database.truncate() call could be seen by other methods run from the same Database handle before the transaction committed, even from other transactions. Environment.truncateDatabase() was introduced to fix the bug without incurring a performance penalty on general operations. [#10339]

  3. Previously, JE provided degree 3 isolation with the exception that it permitted phantom records to appear between calls.  Records that were not seen at one point in transaction A could be seen at a later point in transaction A, if they were inserted by transaction B and transaction B was committed.  Now, phantoms are not permitted as long as both the reader and the inserter are using transactions.  In other words, the current release provides degree 3 isolation with no exceptions.  This isolation level is provided by default when using transactions.  If you wish to optimize by allowing phantom records, the "repeatable read" isolation level may be specified.  For details see TransactionConfig.setRepeatableRead and CursorConfig.setRepeatableRead. [#10477]

  4. JE applications run on Mac OS 1.4.2_* must explicitly set the environment cache size at startup. JE is unable to determine a default cache size because the value returned by Runtime.maxMemory() is unreliable. [#11463]

  5. Change DbDump/DbLoad format. DbLoad now accepts either {true|false} or {0|1} for boolean parameters specified at the start of the file, for compatibility with Berkeley DB dump/load format. DbDump dumps boolean parameters as {0|1}.

    Remove output of database=<name> parameter since we do not allow multiple db dumps. [#10861]

Performance Changes:

  1. A variety of performance enhancements and tuning have increased JE throughput.

  2. Improve the log file cleaner. In some cases the amount of disk space used will be reduced by 50%, but the results will vary depending on your application.  Please be aware that when an environment created with older releases is first opened, the initial cleaning process will take more overhead than usual.  The cleaner may be active for some time as old log files are processed.  If you wish to speed up this initial cleaning process, you may perform a dump-load on all your databases; see the DbDump and DbLoad utilities for details. [#10395]

  3. Improve JE memory management:
    • To improve transactions that hold many locks, JE now includes transactions and lock objects in its calculations of memory consumption.  A transaction that modified many data records and therefore held many locks could cause a java.lang.OutOfMemoryError even though unused memory was available in the JE cache.  This has been corrected. [#10887]

    • The evictor is now run during the last phase of recovery to avoid out-of-memory errors.  This makes it less likely for an application to run out of memory during recovery (while opening an environment) after an abnormal exit. Running out of memory during recovery will only occur if a smaller heap than normally used by the application is specified. [#11076]

    • Improve space utilization by the internal tree.  More user objects will fit in the cache and recovery will use less memory. [#10952]

Copyright (c) 1996-2004 Sleepycat Software, Inc. - All rights reserved.