Upgrading your Application to Ice 3.7.2 from Ice 3.2 or Earlier Releases

In addition to the information provided in Upgrading your Application to Ice 3.7.2 from Ice 3.3, users who are upgrading from Ice 3.2 or earlier should also review this page.

On this page:

Migrating IceStorm databases from Ice 3.2

Ice 3.4 supports the migration of IceStorm databases from Ice 3.1 and from Ice 3.2. Migration from earlier Ice versions may work, but is not officially supported. If you require assistance with such migration, please contact support@zeroc.com.

To migrate, first stop your IceStorm servers.

Next, copy the IceStorm database environment to a second location:

$ cp -r db recovered.db

Locate the correct version of the Berkeley DB recovery tool (usually named db_recover). It is essential that you use the db_recover executable that matches the Berkeley DB version of your existing Ice release. For Ice 3.1, use db_recover from Berkeley DB 4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can verify the version of your db_recover tool by running it with the -V option:

$ db_recover -V

Now run the utility on your copy of the database environment:

$ db_recover -h recovered.db

Change to the location where you will store the database environments for IceStorm 3.4:

$ cd <new-location>

Next, run the icestormmigrate utility. The first argument is the path to the old database environment. The second argument is the path to the new database environment.

In this example we'll create a new directory db in which to store the migrated database environment:

$ mkdir db
$ icestormmigrate <path-to-recovered.db> db

Upon completion, the db directory contains the migrated IceStorm databases.

Migrating IceGrid databases from Ice 3.2

Ice 3.4 supports the migration of IceGrid databases from Ice 3.1 and from Ice 3.2. Migration from earlier Ice versions may work, but is not officially supported. If you require assistance with such migration, please contact support@zeroc.com.

To migrate, first stop the IceGrid registry you wish to upgrade.

Next, copy the IceGrid database environment to a second location:

$ cp -r db recovered.db

Locate the correct version of the Berkeley DB recovery tool (usually named db_recover). It is essential that you use the db_recover executable that matches the Berkeley DB version of your existing Ice release. For Ice 3.1, use db_recover from Berkeley DB 4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can verify the version of your db_recover tool by running it with the -V option:

$ db_recover -V

Now run the utility on your copy of the database environment:

$ db_recover -h recovered.db

Change to the location where you will store the database environments for IceGrid 3.4:

$ cd <new-location>

Next, run the upgradeicegrid.py utility located in the config directory of your Ice distribution (or in /usr/share/Ice-3.4.1 if using an RPM installation). The first argument is the path to the old database environment. The second argument is the path to the new database environment.

In this example we'll create a new directory db in which to store the migrated database environment:

$ mkdir db
$ upgradeicegrid.py <path-to-recovered.db> db

Upon completion, the db directory contains the migrated IceGrid databases.

By default, the migration utility assumes that the servers deployed with IceGrid also use Ice 3.4. If your servers still use an older Ice version, you need to specify the --server-version command-line option when running upgradeicegrid.py:

$ upgradeicegrid.py --server-version 3.2.1 <path-to-recovered.db> db

The migration utility will set the server descriptor attribute ice-version to the specified version and the IceGrid registry will generate configuration files compatible with the given version.

If you are upgrading the master IceGrid registry in a replicated environment and the slaves are still running, you should first restart the master registry in read-only mode using the --readonly option, for example:

$ icegridregistry --Ice.Config=config.master --readonly

Next, you can connect to the master registry with icegridadmin or the IceGrid administrative GUI to ensure that the database is correct. If everything looks fine, you can shutdown and restart the master registry without the --readonly option.

Migrating Freeze databases from Ice 3.2

No changes were made that would affect the content of your Freeze databases. However, we upgraded the version of Berkeley DB, therefore when upgrading to Ice 3.4 you must also upgrade your database to the Berkeley DB 4.8 format. The only change that affects Freeze is the format of Berkeley DB's log file.

The instructions below assume that the database environment to be upgraded resides in a directory named db in the current working directory. For a more detailed discussion of database migration, please refer to the Berkeley DB Upgrade Process.

To migrate your database:

  1. Shut down the old version of the application.
  2. Make a backup copy of the database environment:

    > cp -r db backup.db      (Unix)
    > xcopy /E db backup.db   (Windows)
    
  3. Locate the correct version of the Berkeley DB recovery tool (usually named db_recover). It is essential that you use the db_recover executable that matches the Berkeley DB version of your existing Ice release. For Ice 3.1, use db_recover from Berkeley DB 4.3.29. For Ice 3.2, use db_recover from Berkeley DB 4.5. You can verify the version of your db_recover tool by running it with the -Voption:

    > db_recover -V
    
  4. Use the db_recovertool to run recovery on the database environment:

    > db_recover -h db
    
  5. Recompile and install the new version of the application.
  6. Force a checkpoint using the db_checkpoint utility. Note that you must use the db_checkpointutility from Berkeley DB 4.8 when performing this step.

    > db_checkpoint -1 -h db
    
  7. Restart the application.

Removed APIs in Ice 3.3

This section describes APIs that were deprecated in a previous release and have been removed in Ice 3.3. Your application may no longer compile successfully if it relies on one of these APIs.

Please refer to Removed APIs in Ice 3.4.0 for information on APIs that were removed in Ice 3.4.

Thread per connection

The primary purpose of this concurrency model was to serialize the requests received over a connection, either because the application needed to ensure that requests are dispatched in the order they are received, or because the application did not want to implement the synchronization that might be required when using the thread pool concurrency model.

Another reason for using the thread-per-connection concurrency model is that it was required by the IceSSL plug-ins for Java and C#. This requirement has been eliminated.

The ability to serialize requests is now provided by the thread pool and enabled via a new configuration property:

Ice.ThreadPool.*