---
title: "Upgrade Guide"
url: https://docs.zeroc.com/ice/3.8/upgrade-guide
language: matlab
docs_index: https://docs.zeroc.com/llms.txt
---

> For an index of every page, see [llms.txt](https://docs.zeroc.com/llms.txt).

# Upgrade Guide

Programming language: MATLAB. Other languages: [C++](https://docs.zeroc.com/ice/3.8/upgrade-guide/cpp.md), [C#](https://docs.zeroc.com/ice/3.8/upgrade-guide/csharp.md), [Java](https://docs.zeroc.com/ice/3.8/upgrade-guide/java.md), [JavaScript](https://docs.zeroc.com/ice/3.8/upgrade-guide/js.md), [PHP](https://docs.zeroc.com/ice/3.8/upgrade-guide/php.md), [Python](https://docs.zeroc.com/ice/3.8/upgrade-guide/python.md), [Ruby](https://docs.zeroc.com/ice/3.8/upgrade-guide/ruby.md), [Swift](https://docs.zeroc.com/ice/3.8/upgrade-guide/swift.md).

Learn how to upgrade your application from Ice 3.7 to Ice 3.8.

This page guides you through the upgrade process for an application that uses Ice 3.7. We recommend reading the [Ice 3.8.0 release notes](https://docs.zeroc.com/ice/3.8/releases/ice-3-8-0/release-notes/matlab.md) for a general list of 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

[Supported Platforms for Ice 3.8.3](https://docs.zeroc.com/ice/3.8/releases/ice-3-8-3/supported-platforms.md) lists the operating systems, compilers and language versions that Ice 3.8.3 supports.

## 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. Define your local Slice types directly in your programming language.

### Operations on Classes

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

```diff
class Foo
{
-  void bar();
}
```

A class can no longer implement an interface, and `implements` is no longer a Slice keyword. The Slice compilers also reject a proxy to a class (`Foo*`). Move the operations of such a class to an interface, and replace each proxy to the class with a proxy to that interface.

### Optional Classes

The type of an optional field, parameter, or return value can no longer be a class, or a type that holds class instances such as a sequence of classes or a struct with a class field.

```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!
}
```

An Ice 3.8 application cannot receive an optional class value from an Ice 3.7 application. Stop setting these optional fields, parameters, and return values in your Ice 3.7 applications before you upgrade the applications that receive them.

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

> **Warning**
>
> 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 has been removed. This feature was previously deprecated. Pass a class instance instead: define a class with the fields you need, and use this class as the parameter type.

### Identifier Collisions

A Slice identifier can collide with a keyword or a reserved identifier of a programming language. The Ice 3.7 Slice compilers escaped such an identifier in the generated code. The Ice 3.8 Slice compilers no longer do: they use the Slice identifier as is, and you avoid the collision with the `<lang>:identifier` [metadata](https://docs.zeroc.com/ice/3.8/slice/slice-metadata-directives/matlab.md), which gives a Slice definition another name in the code generated for one language.

For example, `template` is a keyword in C++:

```diff
interface Document
{
-   string template();
+   ["cpp:identifier:getTemplate"] string template();
}
```

The generated C++ function is then named `getTemplate`.

### Deprecated Metadata

The `deprecated` [metadata directive](https://docs.zeroc.com/ice/3.8/slice/deprecating-slice-definitions.md) replaces `deprecate`. The Ice 3.8 Slice compilers still accept `deprecate`, but you cannot apply both to the same definition.

```diff
interface Greeter
{
-   ["deprecate:use greet instead"]
+   ["deprecated:use greet instead"]
    string sayHello();
}
```

## 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](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/matlab.md) 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
```

Set the following properties in an Ice 3.7 application that communicates with Ice 3.8 applications.

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

If you cannot change the configuration of the Ice 3.7 application, disable the idle check in the Ice 3.8 application by setting [EnableIdleCheck](https://docs.zeroc.com/ice/3.8/property-reference/ice-connection-properties/matlab.md) to `0` for the connections to this Ice 3.7 application.

### Connection Timeouts

The Idle Timeout also replaces the connection timeouts of Ice 3.7: the `-t timeout` option in proxy and object adapter endpoints, the `ice_timeout` proxy method, and the `Ice.Default.Timeout` and `Ice.Override.Timeout` properties. Ice 3.8 still accepts `-t timeout` in endpoints for backwards compatibility, but this option no longer has any effect. Remove the calls to `ice_timeout` and the two properties.

Ice 3.8 adds three connection timeouts, for [inactivity](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/matlab.md), [connection establishment](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-establishment/matlab.md) and [graceful closure](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/matlab.md). You configure them with the [Ice.Connection properties](https://docs.zeroc.com/ice/3.8/property-reference/ice-connection-properties/matlab.md); in most cases, the defaults are fine.

### Dispatch Flow Control

By default, Ice 3.8 stops reading from a connection once 100 dispatches of requests received on this connection are in progress, and resumes reading when a dispatch completes. If your application relies on dispatching more requests from one connection concurrently, increase [MaxDispatches](https://docs.zeroc.com/ice/3.8/property-reference/ice-connection-properties/matlab.md). Ice for JavaScript does not implement this limit.

### Default Object Adapter

In Ice 3.7, a client that received callbacks over its outgoing connection called `setAdapter` on this connection. In Ice 3.8, call `setDefaultObjectAdapter` on the communicator instead: the communicator associates this adapter with every outgoing connection it creates afterwards. `setAdapter` remains available for a specific connection. See [Bidirectional Connections](https://docs.zeroc.com/ice/3.8/runtime/connection-management/bidirectional-connections.md).

## Published Endpoints

An object adapter computes its default published endpoints differently in Ice 3.8.

In Ice 3.7, when an endpoint listened on all the network interfaces of the host, the default published endpoints listed the IP address of each interface, some of which could be internal and unreachable. In Ice 3.8, the default published endpoints use a single host: the value of the new `_adapter_.PublishedHost` property, which defaults to the name of the host. See [Object Adapter Endpoints](https://docs.zeroc.com/ice/3.8/runtime/dispatch/object-adapter-endpoints.md).

If you set `_adapter_.PublishedEndpoints` only to limit the published endpoints, try the new default.

The `refreshPublishedEndpoints` method has been removed from `ObjectAdapter`.

## Secure Proxy Options, Properties, and Methods {#secure-proxy-options}

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](https://docs.zeroc.com/ice/3.8/property-reference.md) for a complete list of Ice properties.

The following `IceSSL` properties of Ice 3.7 no longer exist in Ice 3.8, so setting one of them now fails: `IceSSL.CertAuthDir`, `IceSSL.CertAuthFile`, `IceSSL.CertVerifier`, `IceSSL.Ciphers`, `IceSSL.DH.<bits>`, `IceSSL.DHParams`, `IceSSL.EntropyDaemon`, `IceSSL.FindCert.<location>.<name>`, `IceSSL.InitOpenSSL`, `IceSSL.PasswordCallback`, `IceSSL.PasswordRetryMax`, `IceSSL.Protocols`, `IceSSL.ProtocolVersionMax`, `IceSSL.ProtocolVersionMin`, `IceSSL.Random`, `IceSSL.SchannelStrongCrypto`, `IceSSL.SecurityLevel` and `IceSSL.VerifyDepthMax`.

## Communicator Initialization

- The `Application` helper class has been removed from the language mappings that provided it. Create and destroy the communicator in your own code, as described in [Communicator](https://docs.zeroc.com/ice/3.8/runtime/communicator/matlab.md), and shut it down when your application receives Ctrl+C or a termination signal.
- The `dispatcher` field of `InitializationData` is now named `executor`.

## Value Factories

`ValueFactory` and `ValueFactoryManager` have been removed. In Ice 3.7, an application registered a value factory mainly to supply the implementation of a class with operations. Classes no longer have operations, so in most cases you remove your value factories and replace them with nothing. If you still need to create instances of your own classes during unmarshaling, implement a [Slice loader](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/slice-loaders/matlab.md) and set `sliceLoader` on `InitializationData`, or `SliceLoader` in MATLAB.

In Java, the `Ice.Default.Package` and `Ice.Package.module` properties still work, but they are deprecated: we recommend registering a Slice loader in `InitializationData` instead. In Java and MATLAB, a class with a compact ID requires a Slice loader.

## SSL Transport

The SSL transport is now part of the Ice library and is no longer a plug-in.

- Remove the `Ice.Plugin.IceSSL` property from your configuration: Ice 3.8 provides no IceSSL plug-in to load.
- The `IceSSL` certificate API, the certificate verifiers and the password callbacks have been removed. You can still configure the SSL transport with the [IceSSL properties](https://docs.zeroc.com/ice/3.8/property-reference/icessl-properties/matlab.md) in all language mappings except JavaScript, which supports only the secure WebSocket transport (WSS). In C++, C# and Java, we recommend the new [programmatic configuration](https://docs.zeroc.com/ice/3.8/runtime/ssl-transport/matlab.md), which uses the API of the SSL engine of your platform and gives you more control than the properties.

## Plug-ins

The recommended way to install a plug-in has changed in C++, C# and Java: register a plug-in factory in the `pluginFactories` field of `InitializationData`, and Ice creates the plug-in when it initializes the communicator. For example, in C++:

```cpp
Ice::InitializationData initData;
initData.pluginFactories = {IceDiscovery::discoveryPluginFactory()};
```

Your application then uses the plug-in's library like any other library it depends on, and you no longer need an `Ice.Plugin.name` property to load the plug-in.

In the language mappings based on Ice for C++ (MATLAB, PHP, Python, Ruby and Swift), you install a plug-in with an `Ice.Plugin.name` property, as in Ice 3.7. These mappings now include the IceDiscovery and IceLocatorDiscovery plug-ins. You enable them with the properties `Ice.Plugin.IceDiscovery` and `Ice.Plugin.IceLocatorDiscovery`, and you can no longer choose another name for these plug-ins. For example:

```config
Ice.Plugin.IceDiscovery=1
```

See [IceDiscovery](https://docs.zeroc.com/ice/3.8/plugins/icediscovery/matlab.md) and [IceLocatorDiscovery](https://docs.zeroc.com/ice/3.8/plugins/icelocatordiscovery/matlab.md).

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

The buffered mode of the router has been removed. Glacier2 now has a single mode, the unbuffered mode of Ice 3.7, in which the router forwards each request without queuing it. Two features that depended on the buffered mode have been removed with it: request overrides (the `_ovrd` request context), and the batching of requests by the router (`Glacier2.Client.AlwaysBatch` and `Glacier2.Server.AlwaysBatch`).

A session now lasts as long as the connection that created it: the router destroys the session when this connection closes, and relies on the [idle check](https://docs.zeroc.com/ice/3.8/runtime/connection-management/connection-closure/matlab.md) to detect a dead client. The session timeout, `Glacier2.SessionTimeout`, has been removed.

The Glacier2 helper classes (`Glacier2.Application`, `SessionFactoryHelper` and `SessionHelper`) have been removed. Create and destroy the session with the `Glacier2::Router` proxy, as described in [Getting Started with Glacier2](https://docs.zeroc.com/ice/3.8/services/glacier2/getting-started-with-glacier2/matlab.md).

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

The distribution of server files through IcePatch2 has been removed, and with it the `distrib` descriptor; the `dbenv` descriptor has been removed too. An IceGrid 3.8 registry ignores these descriptors in the applications it loads from a 3.7 database, but it no longer accepts the `distrib` and `dbenv` elements in XML: remove them from your descriptor files, remove the `application patch` and `server patch` commands from your `icegridadmin` scripts, and install the files of your servers on each computer with your own tools.

A client or administrative session now lasts as long as the connection that created it. The session timeout, `IceGrid.Registry.SessionTimeout`, has been removed.

The `icegridadmin` command `server state` has been renamed [`server status`](https://docs.zeroc.com/ice/3.8/services/icegrid/icegridadmin-command-line-tool.md): update the scripts that call it.

### 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
```

Update the version in the IceStorm entry point of your IceBox configuration:

```diff
-IceBox.Service.IceStorm=IceStormService,37:createIceStorm
+IceBox.Service.IceStorm=IceStormService,38:createIceStorm
```

The IceStorm Slice definitions of Ice 3.8 are compatible with those of Ice 3.7, with one addition, `createOrRetrieve` on `IceStorm::TopicManager`. 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.

## Dictionaries

A Slice dictionary now maps to a MATLAB `dictionary`. In Ice 3.7, it mapped to a `containers.Map`, or to a struct array with `key` and `value` fields when the key type was a Slice struct.

Create the dictionary with `configureDictionary`, giving the mapped key type and the mapped value type. For example, with `dictionary<long, Employee> EmployeeMap`, where `Employee` is a Slice struct:

```diff
-em = containers.Map('KeyType', 'int64', 'ValueType', 'any');
+em = configureDictionary('int64', 'Employee');
 em(31) = employee;
```

A dictionary keyed by a Slice struct takes the mapped struct as its key. With `dictionary<Point, string> PointNames`:

```diff
-names = struct('key', {}, 'value', {});
-names(1).key = Point(1, 2);
-names(1).value = 'start';
+names = configureDictionary('Point', 'string');
+names(Point(1, 2)) = 'start';
```

When the Slice value type is a sequence, a dictionary, a class or a proxy, the value type of the MATLAB dictionary is `cell`, and each value is a cell that holds the mapped value. Use curly braces to store and retrieve the value itself. With `dictionary<string, Greeter*> GreeterMap`:

```diff
-greeters = containers.Map('KeyType', 'char', 'ValueType', 'any');
-greeters('fr') = greeter;
-greeter = greeters('fr');
+greeters = configureDictionary('string', 'cell');
+greeters{'fr'} = greeter;
+greeter = greeters{'fr'};
```

A request context is a `dictionary` with `string` keys and `string` values:

```diff
-context = containers.Map('KeyType', 'char', 'ValueType', 'char');
+context = configureDictionary('string', 'string');
 context('language') = 'fr';
 greeting = greeter.greet('alice', context);
```

See [Dictionaries](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/dictionaries/matlab.md) for the value type that corresponds to each Slice type.

## String Sequences

A generated proxy method now returns a `sequence<string>` as a string array and accepts a string array for a `sequence<string>` parameter. In Ice 3.7, a `sequence<string>` mapped to a cell array of character vectors. Review the code that indexes a returned sequence with curly braces.

```diff
 names = directory.list();
-first = names{1};
+first = names(1);
```

## Typed Arguments and Properties

A generated proxy method now validates the type of each argument, except for optional parameters. A generated class, exception or struct declares a typed property for each field, except for optional fields and fields that hold class instances.

Pass an empty array of the mapped type for a null proxy or a null class instance. In a typed property, represent a null proxy with an empty array of the proxy type, and an empty sequence with an empty array of the mapped sequence type:

```diff
-registry.setGreeter([]);
-entry.greeter = [];
-entry.weights = [];
+registry.setGreeter(GreeterPrx.empty);
+entry.greeter = GreeterPrx.empty;
+entry.weights = int32.empty;
```

## Struct Properties

In a generated class, exception or struct, a non-optional field of Slice struct type is now empty by default. In Ice 3.7, it held a new instance of the mapped struct, so you could set the fields of this instance directly. Assign an instance first:

```diff
 line = Line();
+line.start = Point();
 line.start.x = 10;
```

## Slice Loaders

Ice 3.8 locates the generated class for a Slice class or exception through a [Slice loader](https://docs.zeroc.com/ice/3.8/slice/user-defined-types/classes/slice-loaders/matlab.md). The default Slice loader maps a Slice type ID such as `::M::Node` to the MATLAB class `M.Node`. It cannot locate a class with a compact ID, or a class or exception whose name or enclosing module you rename with the `matlab:identifier` metadata: for these, create an `Ice.ClassSliceLoader` from the meta classes of the generated classes and give it to the communicator:

```matlab
communicator = Ice.Communicator(args, SliceLoader = Ice.ClassSliceLoader(?Compact, ?CompactExt));
```
