Berkeley DB Java Edition
Release Notes

2.0.90, October 25, 2005

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 release 2.0.90 of Berkeley DB Java Edition, and the fourth release in the JE 2.0 line. Key changes since version JE 1.7.1 are described below; the complete list of changes, along with the release number they appeared in can be found in the change log page for this release.

The change log describes two bug fixes included in this release. In addition, an undocumented cache management setting introduced earlier is described there.

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 2.0 has moved to on-disk file format 3.

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

New Features:

  1. Sequences are now supported in JE. The Sequence API for the JE product is virtually identical to the Sequence API for the Berkeley DB C Edition product. To get started, see the com.sleepycat.je.Sequence class. [#12390]

  2. JE can be used as a J2EE/JCA (Java Connector Architecture) Resource Adapter. For information on how to use the JE J2EE/JCA Resource Adapter with JBoss 3.26 or Sun Java System Application Server 8.1 see JE_HOME/examples/jca/HOWTO-jboss.txt and JE_HOME/examples/jca/HOWTO-sjsas.txt.

  3. JE supports XA Two Phase Commit through the com.sleepycat.je.XAEnvironment class, which implements the javax.transaction.xa.XAResource interface.

  4. JE supplies a ready to install JMX (Java Management Extensions) MBean as well as support for adding JE monitoring to an application's custom MBean. See JE_HOME/examples/jmx/README.txt

  5. Support for read committed (sometimes called degree 2) isolation is now available. Read committed isolation ensures the stability of the current data item read by the cursor, but permits data read by this cursor to be modified or deleted prior to the commit of the transaction. The following new methods and fields are used to configure read committed isolation:

    • TransactionConfig.setReadCommitted and getReadCommitted
    • CursorConfig.setReadCommitted and getReadCommitted
    • CursorConfig.READ_COMMITTED and LockMode.READ_COMMITTED
    • StoredCollections.configuredMap (configuredSet, etc)
    • [#11766]

General Environment Changes:

Changes to Memory Management

The JE evictor, which is responsible for freeing memory in the JE cache, is no longer run as a separate thread. Instead, eviction occurs in-line in all threads that perform database operations. This change avoids potential OutOfMemoryError exceptions in applications with large numbers of threads. Other improvements have also been made to memory budget calculations that avoid potential OutOfMemoryError exceptions.

Eviction is now lighter weight and does less work per operation, resulting in a smoother performance curve for applications running out-of-cache. Out-of-cache applications are applications with a working set that is much larger than the configured JE cache size.

If you are explicitly calling Environment.evictMemory(), or if you are setting the je.env.runEvictor property or any of the je.evictor.* properties, please see the Detailed Evictor Changes section below to understand the potential impact of the changes on your application.

Changes to Log Cleaning

The JE cleaner is responsible for reclaiming disk space by cleaning and deleting JE log files. In past releases the cleaner could become backlogged in some applications. This was particularly true of applications that did not use synced transactions and that had large numbers of writing threads.

In this release the cleaning process is more efficient and the cleaner is able to perform adequately in applications that were problematic in the past. To accomplish this, the cleaner now tracks detailed information about obsolete log entries.

In order for your application to take full advantage of the cleaner improvements, we recommend that you dump and reload the data set using the 2.0 release. This will allow the cleaner to track detailed information for all log entries. To dump/load your database, please see the documentation for the DbDump and DbLoad utilities. If you do not dump/load your data set you will still get the advantage of the cleaner improvements, but the improvements will primarily apply to new data that is written.

If your application calls Environment.cleanLog(), or if you are setting any of the je.cleaner.* properties, please see the Detailed Cleaner Changes section below to understand the potential impact of the changes on your application.

Detailed Evictor Changes

This section is intended for users who are explicitly calling Environment.evictMemory(), or or that are setting the je.env.runEvictor property or any of the je.evictor.* properties.

Because the evictor thread is no longer needed, calling Environment.evictMemory() is also unnecessary for most applications even if the evictor thread was previously disabled by the application. Eviction is performed in-line, whether evictMemory() is called or not. However, evictMemory() can still be called if desired.

je.env.runEvictor is deprecated and is now false by default. The evictor thread can still be run by explicitly setting this property to true, although this is not recommended.

je.evictor.criticalPercentage is also deprecated because it only has meaning if the evictor thread is running; it is now zero by default. If your application is setting je.evictor.criticalPercentage, it is strongly recommended that you remove this setting, or at least change it to zero.

The new je.evictor.evictBytes property replaces je.evictor.useMemoryFloor, which is deprecated and no longer used. evictBytes can be set to the number of bytes to be freed each time the evictor runs, and is 512 KB by default.

The new je.evictor.nodesPerScan property replaces je.evictor.nodeScanPercentage, which is deprecated and no longer used. By default, 10 evictable nodes are scanned for every node is selected for eviction.

The evictBytes and nodesPerScan properties are set to small values by default in order to keep eviction light weight and to reduce the impact on application performance.

je.evictor.evictionBatchPercentage is deprecated and no longer used. In this release, one node is always chosen per scan.

Detailed Cleaner Changes

This section is intended for users who are explicitly calling Environment.cleanLog(), or or that are setting any of the je.cleaner.* properties.

If you are calling Environment.cleanLog() to perform "batch cleaning" (cleaning during periods when the application is less active) it is recommended that you also perform a checkpoint after cleaning. Because a significant amount of cleaner work is deferred to checkpointing and eviction, performing a checkpoint will ensure that batch cleaning is complete. See the javadoc for Environment.cleanLog() for more information.

If you are interested in monitoring cleaner performance, a new cleaner statistic may come in handy: EnvironmentStats.getCleanerBacklog(). This is the number of log files that must be cleaned in order for the cleaner to meet the target utilization (je.cleaner.minUtilization). If this number is zero, the target utilization has been met. If this number is one, the cleaner is cleaning a file but is not backlogged. If this number is greater than one, a backlog exists.

Note that a cleaner backlog is not necessarily a negative thing. For some write intensive applications, a backlog may be necessary in order for the cleaner to keep up with application activity. When there is a cleaner backlog, eviction and checkpointing will pro-actively clean the log files represented by the backlog. This effectively throttles the application until an equilibrium is reached between the cleaner and the application.

As was mentioned above, the cleaner now tracks additional information about obsolete log entries. Although not recommended, this tracking can be disabled by setting je.cleaner.trackDetail to false. This tracking uses some additional disk space, although for a typical application the space used will be 2% or less of the total log.

The cleaner's new detail tracking also uses some additional memory from the JE cache. The upper bound on how much memory is used can be specified using je.cleaner.detailMaxMemoryPercentage, which is 2% by default. This is an upper bound and typically less than this amount will be used by the cleaner.

The new je.cleaner.maxBatchFiles property can be used to specify the maximum size of the cleaner backlog. If zero, the backlog is unlimited. Although not normally recommended, some applications may wish to limit the backlog to improve application performance at the cost of reduced cleaning.

The new je.cleaner.readSize property can be used to specify the size of the cleaner's read buffer. If zero (the default) the je.log.iteratorReadSize property value is used, which is 8 KB by default. Setting the size of cleaner's read buffer to a larger value may improve cleaner performance.

The je.cleaner.retries and je.cleaner.restartRetries are deprecated and no longer used. When a log entry cannot be cleaned because the record is locked, retries take place immediately and no special configuration is needed.

The je.cleaner.cluster and je.cleaner.clusterAll properties are new experimental properties. We recommend that you contact support@sleepycat.com before setting these properties.

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