Version 1.1 of the Ice encoding introduces a convenient new feature that allows you to declare data members and parameters as optional. Collectively called optional values, this feature provides two main benefits for Ice applications:
- It offers a simple and natively-supported mechanism for representing values that may or may not be present, without consuming any additional space in a message when an optional value is not used.
- It significantly improves the ability to gradually evolve components of an Ice application while maintaining backward compatibility with existing deployments.
On this page:
Overview of Optional Values
The optional syntax is the same for both parameters and data members:
optional(tag) type name
optional keyword denotes an optional value with the given tag. The value for
tag must be a non-negative integer.
If your Slice definitions currently use
optional as an identifier, you can continue using it as an identifier by escaping it as
Data members and parameters not marked as optional are considered required; a sender must supply values for all required parameters and members.
Each language mapping defines APIs for passing an optional value, indicating that an optional value is not set, and testing whether an optional value is set. For example, the three strongly-typed languages that Ice currently supports (C++, C#, and Java) all use a similar API: an
Optional type wraps the optional value and provides methods for examining and changing its value. Refer to the language mapping sections for more details on optional values.
A well-behaved program must not assume that an optional data member or parameter always has a value.
An optional value incurs no additional overhead in the encoding when its value is unset. If an optional parameter or member has a value, its overhead depends on several factors, including your choice of tag values.
Optional Parameters in Operations
An operation may declare as optional its return value and any of its parameters. The ordering rules for parameters remain unchanged: all input parameters must precede the output parameters.
The following Slice operation declares a mix of optional and required parameters, as well as an optional return value:
We can invoke
lookup in C++ as shown below:
Optional Data Members in Classes and Exceptions
Data members can be declared as optional in classes and exceptions. Structures do not support optional data members.
Consider the following example:
We can use
Account in C# as shown below:
Implicit conversion operators in C# allow us to pass a value of the declared type, or
Ice.Util.None for an unset value, where an optional value is expected.
Guidelines for using Optional Values
Keep the following guidelines in mind while using optional values:
- Consider an optional value as a logical unit composed of its tag and type. The parameter or member name is not included in the Ice encoding, therefore changes to the name do not affect on-the-wire compatibility. Changing the tag of a value is equivalent to adding a new value: the previous iteration of the value still exists as long as there is at least one deployed program that might use it.
- To change the type of an optional value without affecting compatibility with existing deployments, you must also change its tag. You are essentially deprecating the old value and adding a new one.
- Whenever you change the tag of a value, we recommend making a note of the old definition (such as in a Slice comment) so that you do not accidentally reuse its tag.
- Adding a new optional parameter or member does not affect compatibility with existing deployments as long as its tag is not currently in use.
- Removing an optional parameter or member does not affect compatibility with existing deployments if programs are written correctly to test for the presence of the value prior to using it.
The order of declaration is important for required members and parameters, but is not important for optional members and parameters. If you wish to maintain compatibility with existing deployments, do not change the order of declaration for required members and parameters. Compatibility is not affected by changes to the order of optional members and parameters.
Backward Compatibility with Encoding Version 1.0
Optional values require version 1.1 of the Ice encoding. If the intended receiver only supports version 1.0 of the encoding, the Ice run time in the sender will omit all optional parameters when marshaling the operation's parameters or results, and omit all optional data members. This behavior makes it possible for you to add optional parameters to an operation, or optional members to a class or exception, without affecting backward compatibility with existing deployments that use version 1.0 of the encoding, while gaining the ability to exchange optional values with new deployments that use version 1.1 of the encoding.
For example, suppose existing deployments use the following class definition:
We can safely add an optional member without affecting compatibility:
It is even safe to insert an optional member between two existing members:
When sending an instance of
Person to a receiver that supports only encoding version 1.0, the optional members are omitted and the encoded form matches our initial version of the class.
A similar situation exists for operations. For example, the following three operations are compatible when using encoding version 1.0:
Note however that other types of changes can easily break compatibility.
Using Optional Values Efficiently
The Ice encoding uses a self-describing format to minimize the overhead associated with optional data members and allow for efficient decoding in a receiver. The amount of overhead required for a member depends on the member's type and its tag. The type contributes between one and five bytes of overhead, while the tag value contributes an additional zero to five bytes. Tag values less than 30 add no additional overhead; tag values between 30 and 254 add a single byte, and tag values of 255 or greater add five bytes.
The overhead associated with the member's type is out of your control, but you have direct control of the overhead for tags. To minimize this overhead, use tags in the range zero to 29.
The table below describes the overhead associated with several common Slice types:
|Primitive (including ||1|
|Sequence of ||1|
Refer to the encoding specification for more details on marshaling optional data members.