14.9 Mapping for Exceptions

The mapping for exceptions is based on the inheritance hierarchy shown in Figure 14.1

Figure 14.1. Inheritance structure for exceptions.

The ancestor of all exceptions is System.Exception. Derived from that is Ice.Exception, which provides the definitions of a number of constructors. Ice.LocalException and Ice.UserException are derived from Ice.Exception and form the base of all run-time and user exceptions, respec­tively.

The constructors defined in Ice.Exception have the following signatures:

 

public abstract class Exception : System.Exception
{
    public Exception();
    public Exception(System.Exception ex);
}

Each concrete derived exception class implements these constructors. The second constructor initializes the InnerException property of System.Exception. (Both constructors set the Message property to the empty string.)

Here is a fragment of the Slice definition for our world time server from Section 4.10.5 on page 120 once more:

exception GenericError {
    string reason;
};

exception BadTimeVal extends GenericError {};

exception BadZoneName extends GenericError {};

These exception definitions map as follows:

public partial class GenericError : Ice.UserException
{
    public string reason;

    public GenericError();
    public GenericError(System.Exception ex__);
    public GenericError(string reason);
    public GenericError(string reason, System.Exception ex__);

    // GetHashCode and comparison methods defined here,
    // as well as mapping‑internal methods.
}

public partial class BadTimeVal : M.GenericError
{
    public BadTimeVal();
    public BadTimeVal(System.Exception ex__);
    public BadTimeVal(string reason);
    public BadTimeVal(string reason, System.Exception ex__);

    // GetHashCode and comparison methods defined here,
    // as well as mapping‑internal methods.
}

public partial class BadZoneName : M.GenericError
{
    public BadZoneName();
    public BadZoneName(System.Exception ex__);
    public BadZoneName(string reason);
    public BadZoneName(string reason, System.Exception ex__);

    // GetHashCode and comparison methods defined here,
    // as well as mapping‑internal methods.
}

Each Slice exception is mapped to a C# partial class with the same name. For each exception member, the corresponding class contains a public data member. (Obvi­ously, because BadTimeVal and BadZoneName do not have members, the generated classes for these exceptions also do not have members.)

The inheritance structure of the Slice exceptions is preserved for the generated classes, so BadTimeVal and BadZoneName inherit from GenericError.

All user exceptions are derived from the base class Ice.UserException. This allows you to catch all user exceptions generically by installing a handler for Ice.UserException. Similarly, you can catch all Ice run-time exceptions with a handler for Ice.LocalException, and you can catch all Ice excep­tions with a handler for Ice.Exception.

If an exception (or one of its base exceptions) contains data members, the mapping generates two additional constructors. These constructors allow you to instantiate and initialize an exception in a single statement, instead of having to first instantiate the exception and then assign to its members. For derived excep­tions, the constructors accept one argument for each base exception member, plus one argument for each derived exception member, in base-to-derived order. The second of these constructors has a trailing parameter of type System.Exception which initializes the InnerException property of the System.Exception base exception.

All exceptions also provide the usual GetHashCode and Equals methods, as well as the == and != comparison operators.

The generated exception classes also contain other member functions that are not shown here; these member functions are internal to the C# mapping and are not meant to be called by application code.

Constructors

Exceptions have a default constructor that default-constructs each data member. This means members of primitive type are initialized to the equivalent of zero, and members of reference type are initialized to null. Note that applications must always explicitly initialize a member whose type is a class-mapped structure because the Ice run time does not accept null as a legal value for these types.

If you wish to ensure that data members of primitive and enumerated types are initialized to specific values, you can declare default values in your Slice defini­tion (see Section 4.10.2). The default constructor initializes each of these data members to its declared value.

Exceptions also provide constructors that accept one parameter for each data member. This allows you to construct and initialize a class instance in a single statement (instead of first having to construct the instance and then assigning to its members). For derived exceptions, these constructors accept one argument for each base exception member, plus one argument for each derived exception member, in base-to-derived order.