The subsections below provide additional information about upgrading to Ice 3.5, including administrative procedures for the supported platforms.
On this page:
A discussion of backward compatibility in Ice involves many factors.
Ice maintains source-code compatibility between a patch release (e.g., 3.4.2) and the most recent minor release (e.g., 3.4.0), but does not guarantee source-code compatibility between minor releases (e.g., between 3.4 and 3.5).
The subsections below describe the significant API changes in this release that may impact source-code compatibility. Furthermore, the subsections Removed APIs in Ice 3.5 and Deprecated APIs in Ice 3.5 summarize additional changes to Ice APIs that could affect your application.
As for source-code compatibility, Ice maintains backward binary compatibility between a patch release and the most recent minor release, but does not guarantee binary compatibility between minor releases.
The requirements for upgrading depend on the language mapping used by your application:
Ice always maintains protocol ("on the wire") compatibility with prior releases. A client using Ice version x can communicate with a server using Ice version y and vice versa.
Several features introduced in Ice 3.5 require a new version of the Ice encoding, encoding version 1.1. Older versions of Ice do not understand this encoding: you need to use Ice encoding version 1.0 for communications between clients or servers using Ice 3.5 and clients and servers using older Ice versions. See Encoding Version 1.1 for details.
Upgrading to a new minor release of Ice often includes an upgrade to the supported version of Berkeley DB. In turn, this may require an application to migrate its databases, either because the format of Berkeley DB's database files has changed, or due to a change in the schema of the data stored in those databases.
For example, if your application uses Freeze, it may be necessary for you to migrate your databases even if your schema has not changed.
Certain Ice services also use Freeze in their implementation. If your application uses these services (IceGrid and IceStorm), it may be necessary for you to migrate their databases as well.
Please refer to the relevant subsections below for migration instructions.
Although Ice always maintains compatibility at the protocol level, changing Slice definitions can also lead to incompatibilities. As a result, Ice maintains interface compatibility between a patch release and the most recent minor release, but does not guarantee compatibility between minor releases.
This issue is particularly relevant if your application uses Ice services such as IceGrid or IceStorm, as a change to an interface in one of these services may adversely affect your application.
Interface changes in an Ice service can also impact compatibility with its administrative tools, which means it may not be possible to administer an Ice 3.5.x service using a tool from a previous minor release (or vice-versa).
Starting with Ice 3.2.0, IceGrid registries and nodes are interface-compatible. For example, you can use an IceGrid node from Ice 3.2 with a registry from Ice 3.4.
IceGrid registry replication is only supported between registries using Ice 3.3 or later. With Ice 3.5, since the database format changed, an IceGrid slave from Ice 3.4 or 3.3 will not be able to synchronize with an IceGrid master from Ice 3.5. You need to upgrade all your IceGrid registries to Ice 3.5 to ensure replication between the registries work.
An IceGrid node using Ice 3.5 or later is able to activate a server that uses Ice < 3.5.
Regarding the IceGrid graphical and command-line administrative tools, you must use the 3.5 administrative tools to administer an IceGrid 3.5 registry; you cannot use an administrative tool from an earlier Ice version. The reverse is also true: you cannot administer an IceGrid 3.4 registry with an IceGrid 3.5 administration tool.
Topic linking is supported between all IceStorm versions released after 3.0.0.
In version 1.0 of the Ice encoding, Slice classes and user exceptions are always marshaled in a format that allows a receiver to "slice" an unknown derived type to a known base type. An application that uses Ice 3.4 or earlier may depend on this behavior. For example, the slicing feature makes it possible for a sender to evolve independently of a receiver, adding more derived types that the receiver does not understand without causing the receiver to fail should it encounter one of these new types.
Version 1.1 of the Ice encoding introduces two formats for classes and exceptions. The compact format, which is used by default, does not support the slicing feature, meaning an application that relies on this feature may begin to receive NoObjectFactoryException
or UnknownUserException
errors after upgrading to Ice 3.5. There are several possible solutions:
Ice.Default.EncodingVersion
to 1.0
in all senders and receivers.Ice.Default.SlicedFormat
to 1 in all senders and receivers.The term optional
is now a Slice keyword in Ice 3.5, which means existing Slice definitions that use this term as an identifier will generate an error. To continue using optional
as an identifier, you can use the Slice syntax for escaping keywords:
{zcode:slice} struct Example { bool \optional; }; {zcode} |
The slice2cpp
translator no longer generates C++ comparison operators for all Slice structures. Comparison operators are only generated for structures that qualify as a legal dictionary key type. To generate a comparison operator for a Slice structure that doesn't qualify as such, you can prefix the ["cpp:comparable"]
metadata to your Slice struct definition.
The generated code and supporting classes for the various Ice services are now provided as separate JAR files:
JAR File | Description |
---|---|
Freeze.jar | Freeze classes |
Glacier2.jar | Glacier2 generated code and helper classes |
Ice.jar | The core Ice run time, including the IceSSL plugin |
IceBox.jar | IceBox server, generated code, admin utility |
IceGrid.jar | IceGrid generated code |
IcePatch2.jar | IcePatch2 generated code |
IceStorm.jar | IceStorm generated code |
Also note that the manifest in Freeze.jar
no longer contains a reference to db.jar
, so you may need to update your class path to include db.jar
.
The Eclipse Plug-in still includes only Ice.jar
by default, but you can easily include additional JAR files by changing the Slice2Java properties for your project.
Ice 3.5 adds support for Python 3. Developers who are migrating existing Ice applications from Python 2 to Python 3 should be aware of the following changes that affect the Python language mapping:
str
. Python developers must convert any existing unicode literals and variables into their string equivalents. For Ice developers, a benefit of this unification is that all string values sent "over the wire" are now sent and received as unicode strings. With Python 2.x, the Ice run time behavior remains unchanged: string and unicode values are both accepted as inputs, but only string values are returned as outputs.sequence<byte>
now defaults to the new Python type bytes
. A string value is no longer accepted as a legal value for sequence<byte>
with Python 3.For compatibility with newer PHP releases, the Ice extension no longer supports "call-time" reference arguments when calling Ice_initialize
and Ice_createProperties
. For example, existing applications may invoke Ice_initialize
with an explicit reference argument as follows:
{zcode:php} $communicator = Ice_initialize(&$argv); {zcode} |
The proper way to call this function using Ice 3.5 is shown below:
{zcode:php} $communicator = Ice_initialize($argv); {zcode} |
Ice-specific arguments are now removed from the given argument vector.
IPv6 is now enabled by default on all platforms. You can disable the use of IPv6 in Ice by setting the Ice.IPv6
property to 0
, which may be necessary in environments that lack IPv6 support or on older platforms such as Windows XP. The new property Ice.PreferIPv6Address
determines whether IPv4 or IPv6 addresses take precedence when resolving host names.
Ice 3.5 supports the migration of IceGrid databases from Ice 3.3 and from Ice 3.4. To migrate from earlier Ice versions, you will first need to migrate the databases to the Ice 3.3 format. 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.3, use db_recover
from Berkeley DB 4.6. For Ice 3.4, use db_recover
from Berkeley DB 4.8. 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.5:
$ cd <new-location>
Next, run the upgradeicegrid35.py
utility located in the config
directory of your Ice distribution (or in /usr/share/Ice-3.5
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 $ upgradeicegrid35.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.5. If your servers still use an older Ice version, you need to specify the --server-version
command-line option when running upgradeicegrid35.py
:
$ upgradeicegrid.py --server-version 3.4.2 <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 from Ice 3.5 to ensure that the database is correct. If everything looks fine, you can shutdown and restart the master registry without the --readonly
option.
IceGrid slaves from Ice 3.3 or 3.4 won't interoperate with the IceGrid 3.5 master. You can leave them running during the upgrade of the master to not interrupt your applications. Once the master upgrade is done, you should upgrade the IceGrid slaves to Ice 3.5 using the instruction above.
No changes were made to the database schema for IceStorm in this release. However, you still need to update your databases as described below.
No changes were made that would affect the content of your Freeze databases. However, we upgraded the version of Berkeley DB and the new 1.1 encoding may require that you re-create your indices or set some additional configuration if you use Freeze maps. If you only use Freeze evictors, you only need to upgrade your databases to the new Berkeley DB format. See Encoding Version 1.1.
When upgrading to Ice 3.5, you must upgrade your database to the Berkeley DB 5.3 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:
Make a backup copy of the database environment:
{zcode} > cp -r db backup.db (Unix) > xcopy /E db backup.db (Windows) {zcode} |
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.4, use db_recover
from Berkeley DB 4.8. You can verify the version of your db_recover
tool by running it with the -V
option:
{zcode} > db_recover -V {zcode} |
Use the db_recover
tool to run recovery on the database environment:
{zcode} > db_recover -h db {zcode} |
Force a checkpoint using the db_checkpoint
utility. Note that you must use the db_checkpoint
utility from Berkeley DB 5.3 when performing this step.
{zcode} > db_checkpoint -1 -h db {zcode} |
The majority of Freeze maps will work out of the box with the new 1.1 encoding and without additional configuration. However there are a few cases where you will be required to take special action or add some configuration:
Freeze.DbEnv.<env-name>.EncodingVersion
property to 1.0
to ensure that you decode the keys with the 1.0 encoding and not with the default 1.1 encoding.recreate
method generated on the Freeze map classes by slice2freezej
. See the Freeze Maps documentation for more information.Freeze.DbEnv.<env-name>.EncodingVersion
property to 1.0
to ensure that Freeze still uses the 1.0 encoding for your indices.If you configure your Freeze database environment to use the 1.0 encoding, you will not be able to take advantage of the new features provided with the 1.1 encoding, such as optional values and the new formats for classes. |
Prior versions of the Ice plug-in for Eclipse (including the version released for Ice 3.5b) created a workspace variable named ICE_HOME
that referred to the Ice installation directory configured in Eclipse's Preferences dialog. After adding the Slice2Java builder to a project, the builder updated the project's build path to include Ice JAR files relative to ICE_HOME
. For example, Ice.jar
was configured as the library reference ICE_HOME/lib/Ice.jar
.
As of Ice 3.5.0, the Eclipse plug-in no longer uses the ICE_HOME
variable. Instead, it now uses the workspace variable ICE_JAR_HOME
to refer to the subdirectory containing Ice.jar
, equivalent to the previous setting of ICE_HOME/lib
. Consequently, a new project's build path now includes the library reference ICE_JAR_HOME/Ice.jar
.
The plug-in does not attempt to modify the build path of an existing Ice for Android project to use ICE_JAR_HOME
, nor does it remove ICE_HOME
from the workspace. An existing project can continue to use the ICE_HOME
variable in its build path, but moving or copying the project to a new workspace where ICE_HOME
is no longer defined means the project's build path must be updated.
This section describes APIs whose semantics have changed, potentially in ways that are incompatible with previous releases.
The following APIs were changed in Ice 3.5:
The dynamic invocation and dispatch API now requires encapsulations for input parameters and output results. For example, when calling ice_invoke
, the value for inParams
must be an encapsulation of the input parameters:
{zcode:cpp} Ice::OutputStreamPtr out = Ice::createOutputStream(); out->startEncapsulation(); // marshal parameters out->endEncapsulation(); Ice::ByteSeq inParams; out->finished(inParams); // invoke operation... {zcode} |
Similarly, the byte sequence containing the results must also be an encapsulation:
{zcode:cpp} Ice::ByteSeq results; // invoke operation... Ice::InputStreamPtr in = Ice::wrapInputStream(results); in->startEncapsulation(); // unmarshal results in->endEncapsulation(); {zcode} |
startObject
/endObject
and startException
/endException
.This section describes APIs that were deprecated in a previous release and have now been removed. Your application may no longer compile successfully if it relies on one of these APIs.
The following APIs were removed in Ice 3.5:
Ice.Default.CollocationOptimization
Ice.Default.CollocationOptimized
instead.proxy.CollocationOptimization
proxy.CollocationOptimized
instead.adapter.RegisterProcess
Ice.ServerId
adapter
.RegisterProcess
, this property was used primarily for IceGrid integration and has been replaced by a similar mechanism in the administrative facility.Ice.Trace.Location
Ice.Trace.Locator
.Glacier2.Admin
and IcePatch2.Admin
Ice.Util.generateUUID()
java.util.UUID.randomUUID().toString()
. In C# use System.Guid.NewGuid.ToString()
.Object.ice_hash()
ObjectPrx.ice_getHash()
ObjectPrx.ice_toString()
toString
in Java, ToString
in C#.This section discusses APIs and components that are now deprecated. These APIs will be removed in a future Ice release, therefore we encourage you to update your applications and eliminate the use of these APIs as soon as possible.
The following APIs were deprecated in Ice 3.5:
Stats
facilityThe following components were deprecated in Ice 3.5: