Merge lp:~pbeaman/akiban-persistit/release-notes-3.2.2 into lp:akiban-persistit

[Peter Beaman]

Release nodes and doc updates for 3.2.2. Note that some Javadoc comments needed to change.

LBJ:NO_BUILD

[lp:~pbeaman/akiban-persistit/release-notes-3.2.2]

404. By Peter Beaman on 2012-11-30

Typos and doc tweaks

405. By Peter Beaman on 2012-11-30

Source code cleanup

[Peter Beaman (pbeaman)]

Discussed with Nathan. Approving this to get the release out.

review: Approve

=== modified file 'doc/BasicAPI.rst'
--- doc/BasicAPI.rst	2012-06-11 21:25:37 +0000
+++ doc/BasicAPI.rst	2012-11-30 23:08:31 +0000
@@ -20,14 +20,15 @@
   //
   // register any Coder and Renderer instances before initialization
   //
-  db.initialize(configProperties);
+  db.setConfiguration(config);
+  db.initialize();
   try {
       // do application work
   } finally {
       db.close();
   }
 
-The ``configProperties`` describe the memory allocation, initial set of volumes, the journal, and other settings needed to get Persistit started. See :ref:`Configuration` for details.
+where ``config`` is a ``com.persistit.Configuration`` that describes the memory allocation, initial set of volumes, journal file name, and other settings needed to get Persistit started. The configuration can also be specified as a ``java.util.Properties`` collection, or by name of a properties file. See :ref:`Configuration` for details.
 
 The ``com.persistit.Persistit#close`` method gracefully flushes all modified data to disk, stops background threads and unregisters JMX MBeans. 
 

=== modified file 'doc/BugList'
--- doc/BugList	2012-11-14 15:36:30 +0000
+++ doc/BugList	2012-11-30 23:08:31 +0000
@@ -1,3 +1,43 @@
+1076517 : 3.2.2
+
+`InUseExceptions in stress tests`
+
+Stress tests occasionally experienced InUseExceptions, usually signifying
+a deadlock. Two mechanisms were discovered and fixed. Note that an InUseException
+occurs when an attempt to lock a resource such as a Tree or a Buffer is
+unsatisfied for 60 seconds (the current default timeout).  This exception can
+occur for reasons other than deadlock such as an extraordinarily slow I/O 
+operation or as a result of a debug breakpoint in sensitive code.
+
+1079288 : 3.2.2
+
+`Persistit build success is sensitive to locale`
+
+One Persistit unit test depended on locale-specific text formatting, and therefore
+failed when built in a locale which does not conform to en_US formatting rules. 
+
+1079406 : 3.2.2
+
+`Design flaw makes Persistit needlessly difficult to use in Spring Framework`
+
+Persistit initialization API was modified to make it easy to create and use
+a Persistit instance within Spring Framework.
+
+1081659 : 3.2.2
+
+`isNull(true) leaves Value in unsafe state for stream mode get`
+
+The implementation of isNull(boolean) added in Version 3.2.1 contained a bug that
+made stream-mode get operations fail.
+
+1074372 : 3.2.2
+
+`Stress tests induce RebalanceException`
+
+Code was added to handle a rare situation
+in which removing a key at the boundary between two pages requires one of the pages to split. Formerly this condition
+was not handled properly and instead caused the application thread to receive a RebalanceException.
+
 1076403 : 3.2.1
 
 `NPE while starting AdminUI`

=== modified file 'doc/Configuration.rst'
--- doc/Configuration.rst	2012-09-11 21:02:25 +0000
+++ doc/Configuration.rst	2012-11-30 23:08:31 +0000
@@ -3,14 +3,14 @@
 Configuration
 =============
 
-To initialize Akiban Persistit the embedding application defines a configuration and then invokes one of the  ``com.persistit.Persistit#initialize`` methods. The configuration defines parameters used to determine locations of files, sizes of buffer pool and journal files, policies and other elements required when Persistit starts up. These parameters are managed by the ``com.persistit.Configuration`` class.
+To initialize Akiban Persistit the embedding application specifies a configuration and then invokes the ``com.persistit.Persistit#initialize()`` method. The configuration defines parameters used to determine locations of files, sizes of buffer pool and journal files, policies and other elements required when Persistit starts up. These parameters are managed by the ``com.persistit.Configuration`` class.
 
 An application can define the configuration in one of two equivalent ways:
 
 - Create a ``com.persistit.Configuration`` instance and set its properties through methods such as ``com.persistit.Configuration#setJournalPath``.
 - Specify properties by name in a ``java.util.Properties`` instance and then pass the ``Properties`` to a ``Configuration`` constructor.
 
-The following code samples show different ways of using the ``com.persistit.Persistit#initialize`` method to configure and start Persistit:
+The following code samples show different ways of configuring and starting Persistit:
 
 .. code-block:: java
 
@@ -19,12 +19,14 @@
   p.setProperty("buffer.count.16384", "1000");
   p.setProperty("journalpath", "/home/akiban/data/journal");
   ...
-  db.initialize(p);
+  db.setProperties(p);
+  db.initialize();
 
 .. code-block:: java
 
   final Persistit db = new Persistit();
-  db.initialize("/home/akiban/my_config.properties");
+  db.setPropertiesFromFile("/home/akiban/my_config.properties");
+  db.initialize();
 
 .. code-block:: java
 
@@ -33,7 +35,8 @@
   c.getBufferPoolMap().get(16384).setCount(1000);
   c.setJournalPath("/home/akiban/data/journal");
   ...
-  db.initialize(c);
+  db.setConfiguration(c);
+  db.initialize();
 
 There are three essential elements in a Persistit configuration:
 

=== modified file 'doc/GettingStarted.rst'
--- doc/GettingStarted.rst	2012-08-02 04:51:48 +0000
+++ doc/GettingStarted.rst	2012-11-30 23:08:31 +0000
@@ -48,8 +48,10 @@
       example demonstrating use of Persisit’s multi-version currency control (MVCC) transactions
   ``examples/FindFile``
       a somewhat larger example that uses Persistit as the backing store for file finder utility
-  ``example/PersistitMapDemo``
+  ``examples/PersistitMapDemo``
       demonstration of the PersistitMap interface
+  ``examples/SpringFrameworkExample``
+      configures and initializes a Persistit instance through Spring Framework
 
 HelloWorld
 ----------
@@ -123,7 +125,7 @@
 Initialization and Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Before accessing any data, ``HelloWorld.java`` calls one of the ``com.persistit.Persistit#initialize`` methods of ``com.persistit.Persistit``. This sets up the memory configuration for buffers and the path names of Persistit volume and journal files. Alternative versions of the initialize method accept configuration information from a ``java.util.Properties`` object, from a specified properties file, or by default from the file named ``persistit.properties``.
+Before accessing any data, ``HelloWorld.java`` calls the ``com.persistit.Persistit#initialize()``. This sets up the memory configuration for buffers and the path names of Persistit volume and journal files. Alternative methods accept configuration information from a ``com.persistit.Configuration`` object, a ``java.util.Properties`` object, a specified properties file, or by default from the file named ``persistit.properties`` in the current working directory.
 
 In this example, ``persistit.properties`` looks like this:: 
 

=== modified file 'doc/ReleaseNotes.rst'
--- doc/ReleaseNotes.rst	2012-11-14 15:36:30 +0000
+++ doc/ReleaseNotes.rst	2012-11-30 23:08:31 +0000
@@ -1,5 +1,5 @@
 ************************************
-Akiban Persistit Version 3.2.1
+Akiban Persistit Version 3.2.2
 ************************************
 
 Overview
@@ -50,6 +50,10 @@
 +---------+--------------------+--------------------------------------------------------------------------+
 | Version | Release Date       |  Summary                                                                 |
 +=========+====================+==========================================================================+
+| 3.2.2   | November 30, 2012  | Better support for Spring Framework. Fix rare but serious bugs found in  |
+|         |                    | stress tests. Fix issue related to locale and make sure Persistit builds |
+|         |                    | everywhere.                                                              |
++---------+--------------------+--------------------------------------------------------------------------+
 | 3.2.1   | November 13, 2012  | Fix several low-priority bugs.                                           |
 +---------+--------------------+--------------------------------------------------------------------------+
 | 3.2.0   | October 15, 2012   | Fix several critical and other bugs, one of which requires a modified    |
@@ -79,6 +83,27 @@
 Changes and New Features
 ========================
 
+Persistit 3.2.2 - Spring Framework
+-----------------------------------------------------
+Prior to this release Persistit was needlessly difficult to configure and initialize within Spring Framework.
+This version provides new setter methods and constructors on the com.persistit.Persistit object to allow easy
+injection of configuration properties and make it possible to inject a fully instantiated
+Persistit instance within a Spring project. In addition, new methods were added to the 
+com.persistit.Configuration class to simplify supplying buffer pool and initial volume specifications.
+Three of the ``com.persistit.Persistit#initialize`` methods were deprecated.
+
+This release also adds a new sample application that shows how a configured Persistit instance can be created. For
+Maven users, note that the pom.xml file now includes a dependency on Spring Framework in test scope only; Persistit 
+can still be deployed without any external dependencies.
+
+Persistit 3.2.2 - Bug Fixes
+-----------------------------------------------------
+Version 3.2.2 corrects two issues that were identified through stress tests. For this release
+we added hundreds of hours of stress-testing experience and will continue to invest in ongoing testing.
+
+This version also fixes a unit test with string literals containing numbers formatted according to en_US
+conventions. The test has been corrected and the Persistit build has been tested in several locales.
+
 Persistit 3.2.1 - Bug Fixes
 -----------------------------------------------------
 

=== modified file 'src/main/java/com/persistit/Configuration.java'
--- src/main/java/com/persistit/Configuration.java	2012-11-20 17:45:51 +0000
+++ src/main/java/com/persistit/Configuration.java	2012-11-30 23:08:31 +0000
@@ -45,7 +45,6 @@
 import com.persistit.exception.PersistitIOException;
 import com.persistit.exception.PropertiesNotFoundException;
 import com.persistit.logging.DefaultPersistitLogger;
-import com.persistit.mxbeans.CheckpointManagerMXBean;
 import com.persistit.policy.JoinPolicy;
 import com.persistit.policy.SplitPolicy;
 import com.persistit.util.Util;
@@ -63,13 +62,13 @@
  * <code>Configuration</code>. This object is used directly or indirectly by the
  * following methods:
  * <ul>
- * <li>{@link Persistit#initialize(Configuration)} - uses a supplied
+ * <li>{@link Persistit#setConfiguration(Configuration)} - assigns a supplied
  * <code>Configuration</code> directly.</li>
- * <li>{@link Persistit#initialize(Properties)} - creates and loads a
+ * <li>{@link Persistit#setProperties(Properties)} - creates and loads a
  * <code>Configuration</code> from the supplied <code>Properties</code>.</li>
- * <li>{@link Persistit#initialize(String)} - loads a properties file from the
- * specified file name, and then constructs a <code>Configuration</code> from
- * the loaded <code>Properties</code>.
+ * <li>{@link Persistit#setPropertiesFromFile(String)} - loads a properties file
+ * from the specified file name, and then constructs a
+ * <code>Configuration</code> from the loaded <code>Properties</code>.
  * <li>{@link Persistit#initialize()} - loads a properties file from a default
  * name and then constructs a <code>Configuration</code> from the loaded
  * <code>Properties</code>.
@@ -1160,10 +1159,6 @@
      *            value is invalid.
      * @param str
      *            The string representation, e.g., "100K".
-     * @param min
-     *            Minimum permissible value
-     * @param max
-     *            Maximum permissible value
      * @return The numeric value of the supplied String, as a floag.
      * @throws IllegalArgumentException
      *             if the supplied String is not a valid floating point
@@ -1440,7 +1435,8 @@
      * from an abrupt termination (crash) to take more time.
      * </p>
      * Default size is
-     * {@value CheckpointManagerMXBean#DEFAULT_CHECKPOINT_INTERVAL_S} <br/>
+     * {@value com.persistit.mxbeans.CheckpointManagerMXBean#DEFAULT_CHECKPOINT_INTERVAL_S}
+     * <br/>
      * Property name is {@value #CHECKPOINT_INTERVAL_PROPERTY_NAME}
      */
     public void setCheckpointInterval(final long checkpointInterval) {

=== modified file 'src/main/java/com/persistit/Persistit.java'
--- src/main/java/com/persistit/Persistit.java	2012-11-28 23:13:46 +0000
+++ src/main/java/com/persistit/Persistit.java	2012-11-30 23:08:31 +0000
@@ -2009,7 +2009,7 @@
 
     /**
      * This property can be configured with the configuration property
-     * {@value #TRANSACTION_COMMIT_POLICY_NAME}.
+     * {@value com.persistit.Configuration#COMMIT_POLICY_PROPERTY_NAME}.
      * 
      * @return The default system commit policy.
      */

=== modified file 'src/main/java/com/persistit/Transaction.java'
--- src/main/java/com/persistit/Transaction.java	2012-10-10 16:08:07 +0000
+++ src/main/java/com/persistit/Transaction.java	2012-11-30 23:08:31 +0000
@@ -97,7 +97,7 @@
  * </dl>
  * <p>
  * You can specify a default policy in the Persistit initialization properties
- * using the {@value com.persistit.Persistit#TRANSACTION_COMMIT_POLICY_NAME}
+ * using the {@value com.persistit.Configuration#COMMIT_POLICY_PROPERTY_NAME}
  * property or under program control using
  * {@link Persistit#setDefaultTransactionCommitPolicy} . The default policy
  * applies to the {@link #commit()} method. You can override the default policy