Ice 3.4.2 maintains binary compatibility with Ice 3.4.0 and 3.4.1, therefore it is not necessary for you to recompile your Slice files or your program code, nor is it necessary to relink your application. The database formats used by Ice services such as IceGrid and IceStorm have not changed, therefore no database migration is required. Finally, this release has not removed any APIs. Generally speaking, you are free to use any combination of Ice 3.4.0, Ice 3.4.1, or Ice 3.4.2 applications and Ice services.

The subsections below provide additional information about upgrading to Ice 3.4.2, including administrative procedures for the supported platforms.

On this page:

Upgrading from Ice 3.4.x on Linux (RPMs)

For RPM installations, you can use the Ice 3.4.2 RPMs to upgrade an existing installation of Ice 3.4.0 or 3.4.1.

For a Java application, no additional steps are necessary if your CLASSPATH refers to /usr/share/java/Ice.jar, which is a symbolic link that points to the actual version-specific JAR file.

For a Mono application, the ice-mono RPM for Ice 3.4.2 installs the updated Ice run time assemblies into the Global Assembly Cache (GAC) along with policy assemblies that enable backward compatibility with Ice 3.4.0 and 3.4.1.

Upgrading from Ice 3.4.x on Windows

The file names of the Ice for C++ run time DLLs do not contain the patch number of a release. For example, the core Ice DLL uses the same name (ice34.dll) for Ice 3.4.0, 3.4.1, and 3.4.2. As a result, you can simply substitute the 3.4.2 DLLs for the 3.4.0 or 3.4.1 DLLs. If you install the 3.4.2 DLLs in a different directory, you will typically need to adjust the PATH setting of a C++ application so that it can locate the new libraries. This also applies to Python, Ruby, and PHP applications because they use the Ice for C++ DLLs.

For a Java application, you can replace the existing Ice.jar file with the one from Ice 3.4.2, or you can adjust the CLASSPATH setting to point to the new JAR file.

For a .NET application, Ice for .NET includes policy assemblies that supply the .NET run time with the required compatibility information. Policy assemblies have names of the form policy.3.4.package.dll. For example, the policy assembly for IceBox is policy.3.4.IceBox.dll. One way to upgrade an existing .NET application to a new patch release while maintaining binary compatibility is to install the policy assemblies into the Global Assembly Cache (GAC) using one of the following methods:

Another option is to modify the .config file of your application to add bindingRedirect directives, as explained in the links below:

http://msdn.microsoft.com/en-us/library/7wd6ex19.aspx
http://msdn.microsoft.com/en-us/library/yx7xezcf.aspx

For example, in the .config file of an application you can modify the configuration of the Ice and IceBox assemblies as follows:

{zcode:xml}
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<runtime>
<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

<dependentAssembly>
  <assemblyIdentity name="Ice" culture="neutral" publicKeyToken="cdd571ade22f2f16"/>
  <bindingRedirect oldVersion="3.4.0.0" newVersion="3.4.2.0"/>
  <bindingRedirect oldVersion="3.4.1.0" newVersion="3.4.2.0"/>
</dependentAssembly>

<dependentAssembly>
  <assemblyIdentity name="IceBox" culture="neutral" publicKeyToken="cdd571ade22f2f16"/>
  <bindingRedirect oldVersion="3.4.0.0" newVersion="3.4.2.0"/>
  <bindingRedirect oldVersion="3.4.1.0" newVersion="3.4.2.0"/>
</dependentAssembly>

</assemblyBinding>
</runtime>
</configuration>
{zcode}

This .config file can be used for iceboxnet.exe (as iceboxnet.exe.config), to load a simple IceBox service built with Ice 3.4.0 or 3.4.1 with iceboxnet 3.4.2.

Note that cdd571ade22f2f16 is the token corresponding to ZeroC's public key for signing the assemblies in binary distributions. If you built Ice from sources, your assemblies were signed using the development key instead, which you can find in config/IceDevKey.snk. The token for the development key is 1f998c50fec78381.

The advantage of installing the policy assemblies into the GAC is that they establish binary compatibility for all Ice applications, whereas modifying a .config file must be done for each application individually.

On a development system, it is not necessary to remove your existing Ice installation prior to installing Ice 3.4.2 unless you intend to install Ice 3.4.2 in the same directory as your existing installation. You may need to update your PATH setting and modify your Visual C++ directory configurations to reflect the installation directory for Ice 3.4.2.

Upgrading from Ice 3.4.x with Binary Archives (Mac OS X, Solaris)

The README file included in each binary distribution archive describes how to configure your environment so that the embedded path names in the Ice for C++ shared libraries are resolved correctly. For example, if you extracted the binary distribution for Ice 3.4.1 into /opt/Ice-3.4.1, the README file instructs you to create the following symbolic link:

{zcode}
/opt/Ice-3.4 -> /opt/Ice-3.4.1
{zcode}

To upgrade to Ice 3.4.2, you simply extract the binary distribution archive into /opt/Ice-3.4.2 and reset the symbolic link to point to the new installation:

{zcode}
/opt/Ice-3.4 -> /opt/Ice-3.4.2
{zcode}

No additional steps are necessary for a Java application if its CLASSPATH refers to the JAR file via the symbolic link:

{zcode}
export CLASSPATH=/opt/Ice-3.4/lib/Ice.jar
{zcode}

This also applies for Python and Ruby applications:

{zcode}
export PYTHONPATH=/opt/Ice-3.4/python
export RUBYLIB=/opt/Ice-3.4/ruby
{zcode}

Upgrading from Ice 3.4.x with a Source Distribution (Linux, Mac OS X, Solaris)

If you compiled an Ice 3.4.1 source distribution and installed it via make install, the default installation directory uses a version-specific name such as /opt/Ice-3.4.1. Consequently, you can build and install the Ice 3.4.2 source distribution without affecting your existing Ice 3.4.1 installation.

You may need to update your application's build settings to use the new installation directory for location include and library files. You may also need to update your shared library search path.

The relevant environment variables for each language mapping are detailed below.

Deprecated APIs in Ice 3.4.2

No APIs were deprecated in Ice 3.4.2.

Deprecated APIs in Ice 3.4.1

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.4.1: