Upgrade Guide

Ice 3.8 is new major version of the Ice framework. While maintaining source compatibility with Ice 3.7 was a priority, there are some changes to be aware of when upgrading.

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.

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.

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.

class Foo
{
-  void bar();
}

Optional Classes

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

class Person
{
    string name;
    int number;
}

interface ContactList
{
-    void addContact(Person person, optional(1) Person alias) // error!
}

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.

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.

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

+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 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.

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

-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

Glacier2

TODO

IcePatch2

The IcePatch2 service has been removed.

IceStorm

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

-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

Miscellaneous

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