Skip to main content
Skip table of contents

Upgrade Guide

This page guides you through the upgrade process for an application that uses Ice 3.7. We recommend reading the release notes for a general list changes and improvements.

Ice 3.8 does not maintain binary compatibility or source compatibility with Ice 3.7. When upgrading, you need to recompile your Slice files and in some cases update your source code to use the latest APIs.

Requirements

Please refer to the supported platforms page in the release notes for details on the supported platforms.

Packaging

Many Slice compilers such as slice2cs, slice2swift, etc. are no longer available as part of the general installation of the Linux, macOs, and Windows packages. To use these compilers, install the appropriate language-specific package.

Python Static Code Generation 

The Python static code generation has been improved in Ice 3.8 to follow a more typical Python package layout and to better support type hints.

The following changes may require updates to your projects:

  • The slice2py options --all and --prefix have been removed.

  • The python:package and python:pkgdir metadata directives have been removed.

  • The name and location of Python generated files has changed.

Upgrade Steps

Replacing --all

If you were using --all to automatically compile included Slice files, you must now list all required files explicitly.

Before (3.7):

CODE 
slice2py --all Root.ice

Now (3.8):

CODE 
slice2py Foo.ice Bar.ice Root.ice

Here Foo.ice and Bar.ice represent all files included by Root.ice.

Replacing --prefix

If you used --prefix to control the prefix of generated file names, remove it.

Instead:

  • Use the default mapping for generated modules, and

  • Apply the new python:identifier metadata when you need to remap a generated name (e.g., to avoid a collision with a Python builtin or standard library module).

Replacing python:package

If you used the python:package metadata directive to control the package of a generated module, remove it.

Instead, use python:identifier metadata, which works consistently with all Slice constructs (modules, classes, enums, etc.), not just modules.

DIFF 
-["python:package:zeroc"]
+["python:identifier:zeroc.sys"]
module sys
{
    interface Process
    {
        // ...
    }
}

New File Layout

The Python mapping now generates a Python module for each Slice-defined type, placing it inside a package that corresponds to the Slice module.

SLICE 
module VisitorCenter
{
    interface Greeter
    {
        string greet(string name);
    }
}

Generated output (3.7):

CODE 
./VisitorCenter/__init__.py
./Greeter_ice.py

Generated output (3.8):

CODE 
./VisitorCenter/__init__.py
./VisitorCenter/Greeter_forward.py
./VisitorCenter/Greeter.py

Key points:

  • Generated files no longer use the _ice suffix.

  • All generated files are placed inside the corresponding package directory.

  • For Slice classes and interfaces, an additional <name>_forward.py file is generated for forward declarations.

    Applications do not need to import these _forward modules directly.

Import semantics are unchanged:

CODE 
import VisitorCenter

works the same in 3.7 and 3.8.

Package Imports

In Ice 3.7, Python generated packages would automatically export nested sub-packages.

This is no longer the case in Ice 3.8: you must explicitly import nested packages.

Ice 3.7:

PY 
import Foo

# Nested subpackage is automatically available
c = Foo.Nested.Color.Red

Ice 3.8:

PY 
from Foo import Nested

c = Nested.Color.Red

Or import only what you need:

PY 
from Foo.Nested import Color

c = Color.Red

Slice

Local Slice

Support for local Slice has been removed. Previously defined local Slice types will need to be defined directly in your programming.

Operations on Classes

Support for operations on classes was removed. This feature was previously deprecated.

DIFF 
class Foo
{
-  void bar();
}

Optional Classes

Optional fields or parameters can no longer be a class or contain (including nesting) a class.

DIFF 
class Person
{
    string name;
    int number;
}

interface ContactList
{
-    void addContact(Person person, optional(1) Person alias) // error!
}
DIFF 
class Node
{
    string id;
-   optional(1) Node next; // error!
}

Several upgrade options are available depending on the application needs and constraints.

The following suggestions will break on-the-wire compatibility. Please ensure all clients and servers are using the same Slice definitions.

  1. Replace optional fields or parameters by non-optional ones.

    DIFF 
    class Node
{
    string id;
-   optional(1) Node next;
+   Node next;
}
    DIFF 
    interface ContactList
{
-    void addContact(Person person, optional(1) Person alias)
+    void addContact(Person person, Person alias) 
}

  2. Replace simple classes by structs. This will not be possible for classes which use inheritance or where their usage requires reference semantics.

    DIFF 
    - class Point 
+ struct Point
{
    int x;
    int y;
}

Interface By Value

Support for passing an interface by value was removed. This feature was previously deprecated.

DIFF 
interface Foo 
{ 
-   void passFooByValue(Foo foo); // error!
    void passFooProxy(Foo* foo);
}

Connection Management

Active Connection Management

The connection management system used in Ice 3.7, Active Connection Management (ACM), has been removed. In its place is a new Idle Timeout mechanism which should usually require zero configuration.

The Ice.ACM.* properties have subsequently been removed.

DIFF 
-Ice.ACM.Heartbeat=0
-Ice.ACM.Timeout=1
-Ice.ACM.Close=2

Ice 3.7 applications that wish to interoperate with Ice 3.8 are recommended to set the following properties.

DIFF 
+Ice.ACM.Heartbeat=3
+Ice.ACM.Timeout=60 # or leave unset since 60 is the default

Heartbeat Callback

The setHeartbeatCallback operation has been removed from the Connection class.

Default Object Adapter

A default Object Adapter can now be associated with a Communicator. This greatly simplifies the creation of bidirectional connections. See Bidirectional Connections for more information.

Published Endpoints

The computation of an Object Adapter’s published endpoints has been updated.

With the exception of some filtering for loopback addresses, the previous algorithm would produce endpoints containing the IP addresses for all network interfaces; some of which may be internal and unreachable. The new algorithm is simpler and uses the Fully Qualified Domain Name (FQDN) of the system. See Object Adapter Endpoints for more information.

A new property _adapter_.PublishedHost has been added. It is used to compute the default published endpoints.

Users who are setting _adapater_.PublishedEndpoints to limit the published endpoints are encouraged to try the new default.

Additionally, the refreshPublishedEndpoints method has been removed from ObjectAdapter.

Secure Proxy Options, Properties, and Methods

Removed the secure proxy option, the PreferSecure proxy property, and all associated properties (Ice.Default.PreferSecure, Ice.Override.Secure) and proxy methods (`ice_secure`, `ice_preferSecure`, etc.).

Proxies should not contain a mix of secure and non-secure endpoints.

DIFF 
-ssl -h prod.host.name -p 4062:tcp -h prod.host.name -p 10000
+ssl -h prod.host.name -p 4062

Proxy Creation

Proxy creation has been simplified, allowing you to create a proxy from a communicator and endpoint string.

DIFF 
-proxy = communicator.stringToProxy("greeter: tcp -h localhost -p 4061");
-greeter = GreeterPrx.uncheckedCast(proxy);
+greeter = GreeterPrx(communicator, "greeter:tcp -h localhost -p 4061")

Property Validation

Ice now validates properties with that start with an Ice property prefix (Ice., IceSSL., etc.). Setting an unknown Ice property or a property configured for the wrong Ice service will now fail.

Please refer to the property reference for a complete list of Ice properties.

Services

DataStorm

The DataStorm publisher/subscriber framework has been integrated into the Ice distribution, and is no longer a separate product.

Glacier2

The Slice definitions of Glacier2 are unchanged in Ice 3.8. As a result, you can use a 3.8 router with a 3.7 client, and vice-versa.

IceBox

The Slice definitions of IceBox are unchanged in Ice 3.8.

IceGrid

The Slice definitions of IceGrid in Ice 3.8 are not compatible with the Ice 3.7 definitions. As a result, you cannot mix a 3.8 registry with a 3.7 node, or vice-versa. You also need to use the 3.8 version of the admin tools (icegridadmin and IceGridGUI) to manage a 3.8 deployment.

You can nevertheless:

  • start/manage Ice 3.7 servers from IceGrid 3.8

  • start/manage Ice 3.8 servers from IceGrid 3.7

The IceGrid registry database schema is the same in Ice 3.8 and Ice 3.7. This allows you to start a 3.8 registry with a LMDB database created by a 3.7 registry.

IcePatch2

The IcePatch2 service has been removed.

IceStorm

The IceStorm configuration now uses the IceStorm prefix instead of the IceBox service name as prefix.

DIFF 
-DemoIceStorm.LMDB.Path=db
-DemoIceStorm.TopicManager.Endpoints=tcp -p 9999
-DemoIceStorm.Publish.Endpoints=tcp -p 10000
+IceStorm.LMDB.Path=db
+IceStorm.TopicManager.Endpoints=tcp -p 9999
+IceStorm.Publish.Endpoints=tcp -p 10000

The Slice definitions of IceStorm are unchanged in Ice 3.8. This allows you to use a mix of 3.7 and 3.8 for your IceStorm service, publishers and subscribers. You can even use a mix of 3.7 and 3.8 IceStorm replicas in a replicated deployment.

Moreover, the IceStorm database schema is the same in Ice 3.8 and Ice 3.7. This allows you to start an IceStorm 3.8 service with a LMDB database created by IceStorm 3.7.

Miscellaneous

  • The Objective-C mapping has been removed. You should upgrade to the Swift mapping.

  • The Java Compat mapping has been removed. You should upgrade to the Java mapping.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close