Versioning

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

3 min read

You can change the Slice definitions of an application and keep it compatible with the clients and servers already deployed. This page describes two such changes: adding operations and types, and adding optional parameters and fields.

You can add operations to an existing interface, and add new types, without affecting the clients and servers built with the earlier definitions.

For example, version 1 of the Greeter application defines:

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

Version 2 adds an enumeration and an operation:

Slice
module VisitorCenter
{
enum TimeOfDay { Morning, Afternoon, Night }
interface Greeter
{
string greet(string name);
string greetAtTime(string name, TimeOfDay time);
}
}

Version 1 clients keep working with version 2 servers: version 2 changes nothing that version 1 defines.

A version 2 client that calls greetAtTime on a version 1 server receives an OperationNotExistException, so upgrade the servers before the clients.

You can add an optional parameter to an existing operation without breaking the clients and servers built with the earlier definition. For example, version 2 could instead extend greet:

Slice
module VisitorCenter
{
enum TimeOfDay { Morning, Afternoon, Night }
interface Greeter
{
string greet(string name, optional(1) TimeOfDay time);
}
}

A receiver ignores an optional parameter it does not know, and reads an optional parameter it does not receive as unset:

ClientServertime
version 2
version 2
received
version 2
version 1
ignored; the servant gets name alone
version 1
version 2
unset; the servant handles it, for example with the version 1 greeting

Likewise, you can add optional fields to an existing class or exception.

A client and a server recognize an optional parameter or field by its tag, the number in optional(1), and not by its name. The scope of a tag is an operation, for its parameters and return value, or a class or exception, for the fields it declares. Within this scope:

  • Adding an optional parameter or field with an unused tag is a compatible change.
  • Removing one is a compatible change. Don't reuse its tag while applications built with the earlier definition are still deployed.
  • Making a required parameter or field optional, or an optional one required, is an incompatible change.