Berkeley DB Java Edition 3.1.0 Change Log

The changes between 3.0.12 and 3.1.0 are described directly below. A full list of all changes since JE 2.1.34 is also available below.

Changes since 3.0.12

Log File On-Disk Format Changes:

None.

New Features:

  1. The Direct Persistence Layer is now in GA release. See the Class Evolution feature described in the Direct Persistence Layer section below.

  2. Added a new method, com.sleepycat.je.Database.count(), which has been optimized to execute faster than the count obtained from a database scan. Note that the count may not be accurate in the face of concurrent update operations.

    This functionality is also exposed through the new method com.sleepycat.persist.EntityIndex.count() and is also used by com.sleepycat.collections.StoredMap.size() and com.sleepycat.collections.StoredCollection.size(). See the Javadoc for full details. [#14060]


  3. A new method, EnvironmentConfig.setExceptionListener() provides a notification mechanism for asynchronous exceptions thrown by JE daemon threads. See the Javadoc for more details. [#15018]

General Environment Changes

  1. Added a new Environment configuration parameter: je.adler32.chunkSize to work around JVM memory allocation issues in some versions of Java 1.5 and earlier. By default, JE passes an entire log record to java.util.zip.Adler32 for checksumming. The Sun JVM implementation uses direct memory, which is not managed in the usual way by the garbage collector, and this can cause GC problems when data records are large and there is high concurrency. Setting this parameter will cause JE to pass chunks of the log record to the checksumming class so that the GC does not block. 0 means do not chunk.

    Note that the Adler32 memory allocation issue is reported in this Sun bug entry to be fixed in various releases of the Sun JVM. [#14149]


  2. Invalidate the Environment when an Error such as java.lang.OutOfMemoryError is thrown during database operations, so that RunRecoveryException will be thrown if further operations are attempted. [#14300]

  3. Fixed a bug where high concurrency updates on Java 1.6 could result in this exception from JE daemon threads: com.sleepycat.util.RuntimeExceptionWrapper: Channel closed, may be due to thread interrupt. [#14571]

  4. Fixed a bug that caused a NullPointerException when Database.sync() is called on a newly created, empty deferred-write database. [#14781]

  5. Fixed a bug that caused a NullPointerException in the cleaner thread when running under a JDK1.6 beta. The exception was not fatal, and looked like this: 
    <Cleaner name="Cleaner-1"/> caught exception: java.lang.NullPointerException
java.lang.NullPointerException
        at java.util.TreeMap.getEntry(TreeMap.java:324)
        at java.util.TreeMap.remove(TreeMap.java:580)
        at java.util.TreeSet.remove(TreeSet.java:259)
        at com.sleepycat.je.cleaner.FileSelector.selectFileForCleaning(FileSelector.java:236)
        at com.sleepycat.je.cleaner.FileProcessor.doClean(FileProcessor.java:201)
        at com.sleepycat.je.cleaner.FileProcessor.onWakeup(FileProcessor.java:143)
        at com.sleepycat.je.utilint.DaemonThread.run(DaemonThread.java:189)
        at java.lang.Thread.run(Thread.java:619)
Continuing
    [#14877]

  6. Fixed a bug that resulted in poor cache eviction management, and therefore poor performance when there is a high level of log cleaning in conjunction with a high level of cache eviction. This was a performance regression from the JE 2.1.30 release. One symptom of the problem is that the ratio of EnvironmentStats.getNBINSsStripped() to EnvironmentStats.getNNodesSelected() is lower in 3.0 than in 2.1.30. [#15062]

  7. Fixed a bug that resulted in poor cache eviction management and could trigger OutOfMemoryException. A symptom of the problem is that EnvironmentStats.getCacheDataBytes() could become negative. [#15129]

Direct Persistence Layer

  1. Class evolution is now implemented in the Direct Persistence Layer. For more information please see the release notes and the package specification for the com.sleepycat.persist.evolve package. Also note that if you have deployed a store using the JE 3.0.12 beta release, before changing your persistent classes for the first time you must open and close your store using the JE 3.1 release; see the release notes for more information. [#14762]

  2. Fixed a bug that prevented opening a read-only store when a primary key sequence was used. [#14941]

  3. Fixed a bug that prevented using EntityJoin with read-uncommitted (for example, CursorConfig.READ_UNCOMMITTED). The fix is a change to JE secondary databases that allows a partial DatabaseEntry to be passed as the data parameter to a search method, when using read-uncommitted. [#14966]

  4. Fixed a bug in EntityStore.getStoreNames() which resulted in this stack trace: 
    java.lang.StringIndexOutOfBoundsException: String index out of range: -9
	at java.lang.String.substring(Unknown Source)
	at com.sleepycat.persist.impl.Store.getStoreNames(Store.java:209)
	at com.sleepycat.persist.EntityStore.getStoreNames(EntityStore.java:186)
    [#14978]

  5. Fixed a bug that caused an IllegalArgumentException when calling EntityStore.getSecondaryIndex for a @SecondaryKey that was declared on a superclass of the entity class. [#14978]

  6. The EntityStore.getSubclassIndex method has been added. This method should be used instead of getSecondaryIndex when the secondary key field is in a subclass of an entity class. The index returned by getSubclassIndex is used to access only entities of that subclass. Note that in the previous release, calling getSecondaryIndex in such a situation would fail, and it was necessary to call registerClass as a workaround. [#15102]

  7. A bug was fixed that caused an IllegalArgumentException with the message "Not a key class". This occurred when using a TO_MANY secondary index with a composite key class. The workaround for the bug was to call registerClass for the key class, and this is no longer necessary. [#15103]

API Changes:

  1. Added com.sleepycat.je.jca.ra.JEConnection.removeDatabase(), com.sleepycat.je.jca.ra.JEConnection.truncateDatabase()to support database truncation and removal for JCS users. [#15105]

Utility Changes:

None.

Configuration, Documentation, and Build Changes:

  1. In response to popular demand, the JE jarfile in a JE package is now named je-<version>.jar instead of just je.jar. For example, the jar in this release is named je-3.1.0.jar. [#14669]

Full list of changes since JE 2.1.34

All changes from JE 3.0.11, 3.0.12 and 3.1.0 are listed here.

For additional details, please see the documentation and Release Notes included in your download package or on our website.

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. (3.0.11)

  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. The problem manifests as the following stack trace. A workaround is described below. 
    com.sleepycat.je.DatabaseException: JE 3.0.11: searchResult=class com.sleepycat.
je.tree.IN nodeId=479 nEntries=0
       at com.sleepycat.je.tree.Tree.getParentBINForChildLN(Tree.java:1031)
...
Caused by: java.lang.ClassCastException: com.sleepycat.je.tree.IN
       at com.sleepycat.je.tree.Tree.getParentBINForChildLN(Tree.java:1021)
    (3.0.11)

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. For an introduction to the Direct Persistence Layer API, see Getting Started with the Direct Persistence Layer.

    JE 3.0.11 introduced the beta release of the DPL, while JE 3.1 is the GA release. Please see the Release Notes for more information. [#13894]


  2. A new "deferred write" database mode provides better performance for temporary databases or databases 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.0.11)

  3. com.sleepycat.je.util.DbBackup is a new helper class which simplifies 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](3.0.11)

  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](3.0.11)

  5. The com.sleepycat.bind.tuple package now has bindings that correctly sort negative floating point numbers. See the following new APIs: 
      SortedFloatBinding, SortedDoubleBinding,
  TupleInput.readSortedFloat, TupleInput.readSortedDouble,
  TupleOutput.writeSortedFloat, TupleOutput.writeSortedDouble.
    [#14127](3.0.11)

  6. Added a new method, com.sleepycat.je.Database.count(), which has been optimized to execute faster than the count obtained from a database scan. Note that the count may not be accurate in the face of concurrent update operations.(3.1.0)

    This functionality is also exposed through the new method com.sleepycat.persist.EntityIndex.count() and is also used by com.sleepycat.collections.StoredMap.size() and com.sleepycat.collections.StoredCollection.size(). See the Javadoc for full details. [#14060](3.1.0)


  7. A new method, EnvironmentConfig.setExceptionListener() provides a notification mechanism for asynchronous exceptions thrown by JE daemon threads. See the Javadoc for more details. [#15018](3.1.0)

General Environment Changes:

  1. Shared latches are now used on all internal nodes of the b-tree, which increases concurrency for many operations. Shared latches are only enabled when je.env.sharedLatches is set to true; the default value is false. The default may change in a future release. [#14168](3.0.11)

  2. Fixed a bug where an internal latch was not taken during the deletion of log cleaning metadata or database metadata. [#14214](3.0.11)

  3. Fixed a bug where internal node latches were not released in a corner case where the database has duplicate records and there are concurrent readers and writers. [#14230](3.0.11)

  4. Calling com.sleepycat.je.Transaction.toString() after the transaction was closed resulted in a NullPointerException. This is now fixed. [#14349](3.0.11)

  5. In a corner case requiring a certain pattern of inserts coupled with btree splits and checkpoints, a data record could be lost after an environment recovery following a non-clean shutdown. This has been fixed. [#14424](3.0.11)

  6. The following NullPointerException could be seen when je.cleaner.threads > 0. This has been fixed. 
    
java.lang.NullPointerException
	at com.sleepycat.je.cleaner.UtilizationProfile.getCheapestFileToClean(UtilizationProfile.java:201)
	at com.sleepycat.je.cleaner.FileSelector.selectFileForCleaning(FileSelector.java:205)
	at com.sleepycat.je.cleaner.FileProcessor.doClean(FileProcessor.java:201)
	at com.sleepycat.je.cleaner.FileProcessor.onWakeup(FileProcessor.java:143)
    [#14431](3.0.11)

  7. Cursor.getSearchBothRange() was incorrectly using the custom duplicate key comparator instead of the main btree key comparator, if the database was configured with a custom duplicate comparator. [#14464](3.0.11)

  8. A user reported an OutOfMemoryError in a deployment using fairly large (512K) records. We finally tracked the problem down to the behavior of the standard java.util.zip.Adler32 class, which JE uses to checksum log records. Our research found JVM implementation notes which said that a JVM may temporarily disable garbage collection when executing the native code for Adler32.

    One workaround for the user was to use -Dje.disable.java.adler32=true at runtime. This forces JE to its own, slower Adler32 implementation. It's an existing flag that was used to work around a Java 1.4 problem with the Adler32 implementation.

    A second workaround provided in (3.1.0) is the je.adler32.chunkSize property. Setting this parameter will cause JE to pass chunks of the log record to the checksumming class so that the GC does not block. 0 means do not chunk.

    Note that the Adler32 memory allocation issue is reported in this Sun bug entry to be fixed in various releases of the Sun JVM. [#14149] (3.1.0)


  9. Invalidate the Environment when an Error such as java.lang.OutOfMemoryError is thrown during database operations, so that RunRecoveryException will be thrown if further operations are attempted. [#14300](3.1.0)

  10. Fixed a bug where high concurrency updates on Java 1.6 could result in this exception from JE daemon threads: com.sleepycat.util.RuntimeExceptionWrapper: Channel closed, may be due to thread interrupt. [#14571](3.1.0)

  11. Fixed a bug that caused a NullPointerException when Database.sync() is called on a newly created, empty deferred-write database. [#14781](3.1.0)

  12. Fixed a bug that caused a NullPointerException in the cleaner thread when running under a JDK1.6 beta. The exception was not fatal, and looked like this: 
    <Cleaner name="Cleaner-1"/> caught exception: java.lang.NullPointerException
java.lang.NullPointerException
        at java.util.TreeMap.getEntry(TreeMap.java:324)
        at java.util.TreeMap.remove(TreeMap.java:580)
        at java.util.TreeSet.remove(TreeSet.java:259)
        at com.sleepycat.je.cleaner.FileSelector.selectFileForCleaning(FileSelector.java:236)
        at com.sleepycat.je.cleaner.FileProcessor.doClean(FileProcessor.java:201)
        at com.sleepycat.je.cleaner.FileProcessor.onWakeup(FileProcessor.java:143)
        at com.sleepycat.je.utilint.DaemonThread.run(DaemonThread.java:189)
        at java.lang.Thread.run(Thread.java:619)
Continuing
    [#14877](3.1.0)

  13. Fixed a bug that resulted in poor cache eviction management, and therefore poor performance when there is a high level of log cleaning in conjunction with a high level of cache eviction. This was a performance regression from the JE 2.1.30 release. One symptom of the problem is that the ratio of EnvironmentStats.getNBINSsStripped() to EnvironmentStats.getNNodesSelected() is lower in 3.0 than in 2.1.30. [#15062](3.1.0)

  14. Fixed a bug that resulted in poor cache eviction management and could trigger OutOfMemoryException. A symptom of the problem is that EnvironmentStats.getCacheDataBytes() could become negative. [#15129]

API Changes:

  1. Iterators returned by StoredCollection.iterator() no longer need closing. The original StoredIterator is now available using the new StoredCollection.storedIterator() method. See the Release Notes for more information on collection API changes. [#12986](3.0.11)

  2. Database.entry now supports equals() and hashCode(). [#13778](3.0.11)

  3. Key comparators can now be stored as serialized objects using the new DatabaseConfig.setBtreeComparator(Comparator) and DatabaseConfig.setDuplicateComparator(Comparator) methods. This allows a single comparator class to handle more than one key format. [#14422](3.0.11)

  4. SecondaryDatabase.delete has been corrected to delete all keys (and their associated primary records) in the presence of duplicates. Before, only the first of a duplicate set (and its associated primary) was deleted. Please note this behavior change. [#14506](3.0.11)

  5. Added com.sleepycat.je.jca.ra.JEConnection.removeDatabase(), com.sleepycat.je.jca.ra.JEConnection.truncateDatabase()to support database truncation and removal for JCS users. [#15105]

Utility Changes:

  1. DbVerify will now verify all databases in the environment if the "-s" flag is omitted. In previous versions, "-s" was a mandatory parameter. A new option, "-c" has been added which will check log cleaner metadata. [#14239](3.0.11)

Configuration, Documentation, and Build Changes:

  1. Ant 1.6.0 or later is required to build JE from the provided sources.(3.0.11)

  2. The directions in the installation page on how to compile a non-debug jar were updated.(3.0.11)

  3. The "Writing Transactional Applications" guide has been corrected to make it clear that nested transactions are not yet supported in JE. [#14079](3.0.11)

  4. A variety of problems noted by our faithful readers have been fixed. (3.0.11)

  5. In response to popular demand, the JE jarfile in a JE package is now named je-<version>.jar instead of just je.jar. For example, the jar in this release is named je-3.1.0.jar. [#14669](3.1.0)

Direct Persistence Layer:

  1. Fixed a bug where "UnsupportedOperationException: Class evolution is not supported" was thrown when performing class enhancement. This problem would occur when creating a store without enhancing classes and then using enhancement later, or when creating a store with class enhancement and then not using enhancement later. [#14651](3.0.12)

  2. Fixed a bug where "ArrayIndexOutOfBoundsException: 2147483646" was thrown when updating a record with a secondary key. The problem occurred when a single instance was used for both the primary key and secondary key fields. [#14665](3.0.12)

  3. Fixed a bug where "IllegalArgumentException: Class is not persistent" was thrown for a class that was correctly made persistent using a proxy class. The problem occurred when one proxy class referenced another. [#14665](3.0.12)

  4. Before, if a custom key class (composite key class) was defined but the @KeyField annotation was not included, an UnsupportedOperationException would occur when trying to put() a record, and the exception message was not meaningful. Now, an IllegalArgumentException will occur when getting the index, with a meaningful exception message. [#14673](3.0.12)
  5. Class evolution is now implemented in the Direct Persistence Layer. For more information please see the release notes and the package specification for the com.sleepycat.persist.evolve package. Also note that if you have deployed a store using the JE 3.0.12 beta release, before changing your persistent classes for the first time you must open and close your store using the JE 3.1 release; see the release notes for more information. [#14762]

  6. Fixed a bug that prevented opening a read-only store when a primary key sequence was used. [#14941]

  7. Fixed a bug that prevented using EntityJoin with read-uncommitted (for example, CursorConfig.READ_UNCOMMITTED). The fix is a change to JE secondary databases that allows a partial DatabaseEntry to be passed as the data parameter to a search method, when using read-uncommitted. [#14966]

  8. Fixed a bug in EntityStore.getStoreNames() which resulted in this stack trace: 
    java.lang.StringIndexOutOfBoundsException: String index out of range: -9
	at java.lang.String.substring(Unknown Source)
	at com.sleepycat.persist.impl.Store.getStoreNames(Store.java:209)
	at com.sleepycat.persist.EntityStore.getStoreNames(EntityStore.java:186)
    [#14978]

  9. Fixed a bug that caused an IllegalArgumentException when calling EntityStore.getSecondaryIndex for a @SecondaryKey that was declared on a superclass of the entity class. [#14978]

  10. The EntityStore.getSubclassIndex method has been added. This method should be used instead of getSecondaryIndex when the secondary key field is in a subclass of an entity class. The index returned by getSubclassIndex is used to access only entities of that subclass. Note that in the previous release, calling getSecondaryIndex in such a situation would fail, and it was necessary to call registerClass as a workaround. [#15102]

  11. A bug was fixed that caused an IllegalArgumentException with the message "Not a key class". This occurred when using a TO_MANY secondary index with a composite key class. The workaround for the bug was to call registerClass for the key class, and this is no longer necessary. [#15103]

  12. An optional verbose option was added to the ClassEnhancer to print the name of each class file that is enhanced. See ClassEnhancer for more information. [#14680](3.0.12)

  13. Class evolution is now implemented in the Direct Persistence Layer. For more information please see the release notes and the package specification for the com.sleepycat.persist.evolve package. Also note that if you have deployed a store using the JE 3.0.12 beta release, before changing your persistent classes for the first time you must open and close your store using the JE 3.1 release; see the release notes for more information. [#14762](3.1.0)

  14. Fixed a bug that prevented opening a read-only store when a primary key sequence was used. [#14941](3.1.0)

  15. Fixed a bug that prevented using EntityJoin with read-uncommitted (for example, CursorConfig.READ_UNCOMMITTED). The fix is a change to JE secondary databases that allows a partial DatabaseEntry to be passed as the data parameter to a search method, when using read-uncommitted. [#14966](3.1.0)

  16. Fixed a bug in EntityStore.getStoreNames() which resulted in this stack trace: 
    java.lang.StringIndexOutOfBoundsException: String index out of range: -9
	at java.lang.String.substring(Unknown Source)
	at com.sleepycat.persist.impl.Store.getStoreNames(Store.java:209)
	at com.sleepycat.persist.EntityStore.getStoreNames(EntityStore.java:186)
    [#14978](3.1.0)

  17. Fixed a bug that caused an IllegalArgumentException when calling EntityStore.getSecondaryIndex for a @SecondaryKey that was declared on a superclass of the entity class. [#14978](3.1.0)

  18. The EntityStore.getSubclassIndex method has been added. This method should be used instead of getSecondaryIndex when the secondary key field is in a subclass of an entity class. The index returned by getSubclassIndex is used to access only entities of that subclass. Note that in the previous release, calling getSecondaryIndex in such a situation would fail, and it was necessary to call registerClass as a workaround. [#15102](3.1.0)

  19. A bug was fixed that caused an IllegalArgumentException with the message "Not a key class". This occurred when using a TO_MANY secondary index with a composite key class. The workaround for the bug was to call registerClass for the key class, and this is no longer necessary. [#15103](3.1.0)

Workaround for upgrade issue between JE 2.0.90 and JE 2.1.30

If you are upgrading from a release of JE that is 2.0.90 or earlier, then you should ensure that you call Environment.close() prior to upgrading. If you do not close the environment cleanly, and you have very recently created a new database, you may see the following exception: 

com.sleepycat.je.DatabaseException: JE 3.0.11: searchResult=class
com.sleepycat. je.tree.IN nodeId=479 nEntries=0
      at com.sleepycat.je.tree.Tree.getParentBINForChildLN(Tree.java:1031)
...
Caused by: java.lang.ClassCastException: com.sleepycat.je.tree.IN
       at
       com.sleepycat.je.tree.Tree.getParentBINForChildLN(Tree.java:1021)

The data in the environment was not corrupted, and the environment can be successfully opened with the following steps which remove any new files create by JE 3.0.11, and then call Environment.close() prior to upgrading.

To remove any data created by JE 3.0.11:

To close the environment cleanly after any JE 3.0.11 data has been removed: