Berkeley DB Java Edition
Release Notes

3.0.12, May 25, 2006

These release notes contain:

• Overview
• New in this Release

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.

The documentation set for JE includes:

• 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 description of how to use JE and the new Direct Persistence Layer, see the Getting Started with the Direct Persistence Layer guide.
• For a description of how to use JE and the Sleepycat Java Collections API, see the collections tutorial.
• For an overview on using transactions, see Writing Transactional Applications with Berkeley DB, Java Edition
• For a complete description of the JE API set, see the Javadoc.

New in this Release

This is release 3.0.12 of Berkeley DB Java Edition, and the second release in the JE 3.0 line. JE 3.0.12 contains bug fixes to the Direct Persistence Layer beta released in JE 3.0.11, and are described in the first section of the change log page for this release.

In JE 3.0.11 we introduced a new Plain Old Java Object (POJO)-based persistent object model which we called the Persistence API. Since then, we've decided to rename this API to the Direct Persistence Layer, to avoid confusion with the EJB3 Java Persistence API.

Key changes since version JE 2.1.30 are described below; the complete list of changes can also be found in the change log page.

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 3.0.11 has moved to on-disk file format 4.
   
   The change is forward compatible in that JE files created with release 2.1.30 and earlier can be read when opened with JE 3.0.11. The change is not backward compatible in that files created with JE 3.0.11 cannot be read by earlier releases. Note that if an earlier environment is opened read/write, a new log file is written by JE 3.0.11 and the environment can no longer be read by earlier releases.


2. An upgrade problem was inadvertently introduced between JE 2.0.90, which was released in Nov 1, 2005 and the following JE 2.1.34 release in January 2006. The problem does not apply to you if you have an environment created with JE 2.0.90 or earlier, and have since successfully opened it with JE 2.1.30. Likewise, a 2.0.90 and earlier environment that has been closed cleanly with Environment.close() will not encounter this problem, nor will most environments that have more than 30 Mb of data. Please read the the change log page for the full description.

New Features:

1. A new Direct Persistence Layer adds a built-in Plain Old Java Object (POJO)-based persistent object model, which provides support for complex object models without compromises in performance. [#13894]

   No object bindings are needed when using the Direct Persistence Layer and Java annotations can be used to define persistent classes and index keys. Bindings are generated automatically based on annotations, and bytecode enhancement is used to avoid the overhead of reflection.

   Starting points for using the Direct Persistence Layer are: Getting Started with the Direct Persistence Layer and the com.sleepycat.persist package specification.

   This is a beta release of the Direct Persistence Layer. Please be aware of the following limitations of the beta release:

   • Although class evolution is described in the API documentation, it is not supported in the beta release. While using the beta release, if you change your persistent class field definitions then you will need to delete any existing environments that were created using the old class definitions.
   
   
   • Class evolution will be fully supported in the final release of the Direct Persistence Layer. When upgrading to the final release, you may be required to convert your data files.
   
   
   • The beta release does not support using the java.math.BigInteger or java.math.BigDecimal classes as persistent types. These classes will be supported as simple types in the final release, and may be used as primary and secondary keys.
   
   
   • The beta release of the Direct Persistence Layer requires compiling and deploying with Java 1.5 or greater. Support for Java 1.4 may be added in a future release, based on user demand.


2. A new "deferred write" database mode provides better performance for temporary databases or database which rapidly modify data by reducing the amount of I/O incurred. In a normal durable database, every new version of a data record is written to disk; in deferred write mode, JE avoids disk I/O until cache is exceeded or Database.sync() is called. See the Getting Started Guide, Chapter 3 (Databases) for more information. [#13936]


3. com.sleepycat.je.util.DbBackup is a new helper class which simplified backups by managing JE background activity in an open environment. See the Getting Started Guide, Chapter 7 (Backing up and Restoring Berkeley DB Java Edition Applications) and the Javadoc for DbBackup for more information. [#14022]


4. The com.sleepycat.collections package is now fully compatible with the Java Collections framework. In previous releases, Collections.size() was not supported, and collection iterators had to be explicitly closed. These incompatibilities have been addressed to provide full interoperability with other Java libraries that use the Java Collections Framework interfaces. [#14154] [#12986]

   Please be aware of the following changes:

   • In prior releases, because Collections.size() was not supported, certain operations that worked with standard collections were not possible with stored collections. For example, a stored collection could not be passed to the constructor of a standard collection such as ArrayList, HashSet, etc, because these constructors call Collection.size(). Using these constructors is now possible.
   
   
   • In prior releases, because iterators had to be closed, stored collections could not be passed to external library methods that obtained an iterator, such as Collection.containsAll, Collection.addAll, etc. Using such methods is now possible. Using the Java 1.5 "foreach" statement with stored collections is also now possible.
   
   
   • The changes to the collections API are compatible with prior releases, with one exception: The Iterator object returned by the StoredCollection.iterator() method can no longer be explicitly cast to StoredIterator because a different implementation class is now used for iterators. If you depend on the StoredIterator class, you must now call StoredCollection.storedIterator() instead. Note that the StoredIterator.close(Iterator) static method is compatible with the new iterator implementation, so no changes are necessary if you are using that method to close iterators.
   
   
   • In order to provide iterators that do not require closing, the Collection.iterator method now returns iterators that retrieve records in blocks. An underlying Cursor is not kept open by the iterator. The block of records is cached and returned by the iterator as required. When a record is needed outside the cached block, another block of records is retrieved. If desired, you can configure the number of records per block by calling the new method StoredCollection.setIteratorBlockSize.
   
   
   • The performance of the Collection.size method depends on the size of the underlying database. All non-duplicate records in the database are enumerated by this method, bringing them into memory if they are not already cached. To maximize performance and concurrency, no locks are taken on records as they are counted.
   
   
   • Note that if other threads are adding or removing records while the size() method is executing, the size returned may be incorrect, because the size method does not lock the database. This behavior is compatible with the standard Collection.size interface contract.

General Environment Changes:

See the change log contains the complete and detailed description of all bug fixes.

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