MapGuide RFC 23 - Berkeley DB XML 2.3 Upgrade

This page contains a change request (RFC) for the MapGuide Open Source project. More MapGuide RFCs can be found on the RFCs page.

Status

RFC Template Version	(1.0)
Submission Date	July 3, 2007
Last Modified	Steve Dang Timestamp
Author	Steve Dang
RFC Status	adopted
Implementation Status	under development
Proposed Milestone	2.0
Assigned PSC guide(s)	(when determined)
Voting History	July 24, 2007
+1	Tom, Jason, Andy, Bob, Haris, Bruce
+0
-0
-1

Overview

This RFC updates MapGuide to use the latest version of Berkeley DB XML.

For details, refer to Berkeley DB XML 2.3 release notes:

​http://www.oracle.com/technology/documentation/berkeley-db/xml/relnotes.html

Motivation

There was some report from the user group that the MapGuide repositories got corrupted (though recoverable). The Berkeley DB XML 2.3 upgrade could help minimize such incident.

The benefits of Berkeley DB XML 2.3 release include conformance to W3C recommendations for XQuery 1.0 and XPath 2.0, bug fixes, and performance improvements:

​http://www.oracle.com/technology/documentation/berkeley-db/xml/change-log.html

Proposed Solution

Modifications need to be made to the MapGuide server and its installer:

1. The server will detect a version mismatch at startup, and throw an exception along with instructions on how to upgrade.

Like other exceptions thrown at startup time, this Version Mismatch exception will stop the server from running:

• If the server is running as a service, then the error will be logged and available to the user for viewing (i.e. via the server log file or the event viewer).
• If the server is running as an application, then the error will be logged and displayed on the console/terminal window.

The error message will include a brief description about the problem and a reference to the detailed upgrade documentation.

2. During setup, the installer will back up the existing repositories if necessary, then run the upgrade utilities (which will do nothing if the repositories have already been upgraded). In rare/complex situation, the installer may encounter some upgrade problem (e.g. different combinations of versions of repositories, including no longer supported ones, etc.). When this happens, the installer will continue the installation without the upgrade, and at the end, it will display a brief description about the problem and a reference to the detailed upgrade documentation. Note that, the installer will need to install the upgrade utilities so that they can be run independently at a later time. This is useful when:

• The version mismatch detected by the server or the upgrade problem encountered by the installer does occur.
• The user would like to restore previously backed up repositories, then upgrade them without rerunning the installer.

Implications

• The database format has been changed and there is no way to revert the upgrade, so the repositories must be backed up.
• There have been 5 patches for Berkeley DB XML 2.3 release which will be included with the upgrade:

​http://www.oracle.com/technology/products/berkeley-db/xml/update/2.3.10/patch.2.3.10.html

• Any new Berkeley DB XML defect found during development will be fixed and reported to Oracle.

Test Plan

Tests need to be done after the upgrade:

• Resource Service unit tests must all pass.
• Scripts that back up, restore, and recover repositories must run successfully.

Funding/Resources

Supplied by Autodesk.