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:
- 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:
- 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:
- The environment cache size properties (je.maxMemory and
je.maxMemoryPercent) can now be changed by the application after
opening the environment. [#11337]
- 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]
- 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]
- 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]
- 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:
- A variety of performance enhancements and tuning have increased
JE throughput.
- 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]
- 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.